<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">

<head>
<meta http-equiv="Content-Language" content="en-us" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Welcome to BLTsville</title>
<style type="text/css">
.cmd_line {
	background: #000;
	color: #fff;
	padding: 10px;
}
.inline_code {
	font-family: "Courier New", Courier, monospace;
	font-size: small;
}
.code_block {
	margin-left: 40px;
	font-family: "Courier New", Courier, monospace;
	font-size: small;
}
.small_code_block_in_table {
	font-family: "Courier New", Courier, monospace;
	font-size: x-small;
}
.small_code_block {
	font-family: "Courier New", Courier, monospace;
	font-size: x-small;
	margin-left: 40px;
}
.underline_code {
	font-family: "Courier New", Courier, monospace;
	font-size: small;
	text-decoration: underline;
}
.Code_Header {
	font-size: xx-large;
	font-weight: bold;
	text-align: left;
	font-family: "Courier New", Courier, monospace;
}
.Code_Header_2 {
	font-size: x-large;
	font-weight: bold;
	text-align: left;
	font-family: "Courier New", Courier, monospace;
}
.Code_Header_3 {
	font-size: large;
	font-weight: bold;
	text-align: left;
	font-family: "Courier New", Courier, monospace;
}
.imponly {
	border: thin solid #666666;
	margin-left: 40px;
	background-color: #E5E5E5;
	font-family: Arial, Helvetica, sans-serif;
	color: #333333;
}
.Header1 {
	margin: 0px 0 0 0;
	font-size: xx-large;
	font-weight: bold;
	text-align: left;
	line-height: normal;
	background-color: #E0E0E0;
}
.Header2 {
	font-size: xx-large;
	font-weight: bold;
	margin: 0px;
	line-height: 100%;
}
.Header3 {
	font-size: x-large;
	font-weight: bold;
	margin: 0px;
	line-height: 100%;
}
.Header4 {
	font-size: large;
	font-weight: bold;
	margin: 0px;
	line-height: 100%;
}
.strong_emphasis {
	text-decoration: underline;
	font-weight: bold;
}
.filename {
	font-family: Arial, Helvetica, sans-serif;
	font-size: small;
}
.underline {
	text-decoration: underline;
}
.grn_left {
	text-align: left;
	color: #009900;
}
.left_topbord {
	text-align: left;
	border-top-style: solid;
	border-top-width: 1px;
}
.center_topbord {
	text-align: center;
	border-top-style: solid;
	border-top-width: 1px;
}
.blue_left_botbord {
	text-align: left;
	border-bottom-style: solid;
	border-bottom-width: 1px;
	color: #0000FF;
}
.blue_center_botbord {
	text-align: center;
	border-bottom-style: solid;
	border-bottom-width: 1px;
	color: #0000FF;
}
.red_center {
	text-align: center;
	color: #FF0000;
}
.red_left {
	text-align: left;
	color: #FF0000;
}
.grn_center {
	text-align: center;
	color: #009900;
}
.red_center_topbord {
	text-align: center;
	border-top-style: solid;
	border-top-width: 1px;
	color: #FF0000;
}
.blu_center_topbord {
	text-align: center;
	border-top-style: solid;
	border-top-width: 1px;
	color: #0000FF;
}
.indent_thick_bord {
	border-color: #000000;
	border-style: solid;
	margin-left: 40px;
}
.thin_bord {
	border-style: solid;
	border-width: 1px;
}
.thin_bord_dbl_botbord {
	border-left-style: solid;
	border-left-width: 1px;
	border-right-style: solid;
	border-right-width: 1px;
	border-top-style: solid;
	border-top-width: 1px;
	border-bottom-style: double;
	border-bottom-width: 3px;
}
.dl_link {
	float: right;
}
.note {
	font-family: Arial, Helvetica, sans-serif;
	font-weight: bold;
	margin-left: 40px;
}
.small_note {
	font-size: xx-small;
	line-height: 100%;
}
.ctr {
	text-align: center;
}
.glyph_cache {
	font-family: "Courier New", Courier, monospace;
	font-size: medium;
	font-weight: normal;
	font-style: normal;
	margin-left: 40px;
	background-color: #000000;
	color: #FFFFFF;
}
.example {
	border-style: solid;
	border-width: 1px;
	margin-left: 40px;
	margin-right: 40px;
}
.rt_thick_bord {
	border-right-style: solid;
	border-right-color: #000000;
}
.indent {
	margin-left: 40px;
}
.ctr_thin_bord {
	border-style: solid;
	border-width: 1px;
	text-align: center;
}
.indent_thin_bord {
	border-style: solid;
	border-width: 1px;
	margin-left: 40px;
}
.bold_sans {
	font-family: Arial, Helvetica, sans-serif;
	font-weight: bold;
}
.nowrap {
	border-style: solid;
	border-width: 1px;
	white-space: nowrap;
	font-size: small;
}
</style>
</head>

<body>

<table style="width: 100%; line-height: 100%;">
	<tr>
		<td style="width: 484px">
		<table>
			<tr>
				<td>
				<div style="background-position: center; background-image: url('bvlogo.png'); width: 484px; height: 400px; background-repeat: no-repeat;">
					<div style="position: relative; left: 0; top: 0;">
						<a href="http://graphics.github.com/ocd">
						<img src="ocdtab.png" alt="Now With OCD" style="border-width: 0; position: absolute; top: 0; right: 0;" /></a>
					</div>
				</div>
				</td>
			</tr>
			<tr>
				<td class="ctr"><span class="Header2">Version 2.2</span></td>
			</tr>
		</table>
		</td>
		<td>
		<p>BLTsville is the open 2-D API designed to provide an abstract interface for both hardware and software 2-D implementations.</p>
		<p>BLTs (BLock Transfers) involve the moving around of blocks (rectangles) of pixels.&nbsp; BLTsville is the place 
		to go for BLTs.</p>
		<hr />
		<table style="width: 100%">
			<tr>
				<td>
				<div class="dl_link">
					<img alt="CC BY-ND" longdesc="Creative Commons Attribution-NoDerivs 3.0 Unported License" src="http://i.creativecommons.org/l/by-nd/3.0/88x31.png" width="88" height="31" /></div>
				<p class="Header2">License</p>
				</td>
			</tr>
			<tr>
				<td>
				<div>
					<p class="small_note">The API is designed and maintained by Texas Instruments, Inc., but anyone is free 
					to use it with no cost or obligation.</p>
					<p>This project is licensed under the <a href="http://creativecommons.org/licenses/by-nd/3.0/">Creative 
					Commons Attribution-NoDerivs 3.0 Unported License</a> (user mode), and the
					<a href="http://www.gnu.org/licenses/gpl-2.0.html">GNU General Public License version 2</a> (kernel 
					mode).</p>
				</div>
				</td>
			</tr>
		</table>
		<hr />
		<table style="width: 100%">
			<tr>
				<td>
				<p class="Header2">Dependencies</p>
				</td>
			</tr>
			<tr>
				<td>
				<p>This project is dependent on the <a href="http://graphics.github.com/ocd">Open Color format Defintions 
				(OCD) project</a>.</p>
				</td>
			</tr>
		</table>
		<hr />
		<table style="width: 100%">
			<tr>
				<td>
				<p class="Header2">Source</p>
				</td>
			</tr>
			<tr>
				<td>
				<div class="dl_link">
					<a href="http://github.com/graphics/bltsville/zipball/master">
					<img width="90" alt="download zip" src="http://github.com/images/modules/download/zip.png" /></a>
					<a href="http://github.com/graphics/bltsville/tarball/master">
					<img width="90" alt="download tar" src="http://github.com/images/modules/download/tar.png" /></a>
				</div>
				<div>
					Get the source code (headers) from GitHub at <a href="http://github.com/graphics/bltsville">github.com/graphics/bltsville</a>, 
					or download the project in <a href="http://github.com/graphics/bltsville/zipball/master">zip</a> or
					<a href="http://github.com/graphics/bltsville/tarball/master">tar</a> format.</div>
				<p>You can also clone the project with <a href="http://git-scm.com">Git</a> by running:</p>
				<pre><a class="cmd_line">$ git clone git://github.com/graphics/bltsville</a></pre>
				</td>
			</tr>
			<tr>
				<td><hr />
				<table style="width: 100%">
					<tr>
						<td class="Header2">Wiki</td>
					</tr>
					<tr>
						<td><a href="https://github.com/graphics/bltsville/wiki">https://github.com/graphics/bltsville/wiki</a></td>
					</tr>
				</table>
				</td>
			</tr>
		</table>
		</td>
	</tr>
</table>
<hr />
<p class="Header1">Points of Interest in BLTsville</p>
<table style="width: 100%">
	<tr>
		<td style="width: 50%" valign="top">
		<ul>
			<li>Solid fills</li>
			<li>Pattern fills</li>
			<li>Copies</li>
			<li>Color format conversion<ul>
				<li>Extensive color format support<ul>
					<li>RGB, BGR</li>
					<li>RGBA, ARGB, etc.</li>
					<li>YCbCr (YUV)<ul>
						<li>subsampling</li>
						<li>packed</li>
						<li>planar</li>
					</ul>
					</li>
					<li>Monochrome</li>
					<li>Alpha-only</li>
					<li>Look-Up Table (LUT)</li>
				</ul>
				</li>
				<li>Extensible color format</li>
			</ul>
			</li>
			<li>ROP4<ul>
				<li>Three inputs</li>
			</ul>
			</li>
			<li>Blends<ul>
				<li>Pre-defined Porter-Duff blends</li>
				<li>Pre-defined DirectFB support</li>
				<li>Extensible blends</li>
			</ul>
			</li>
			<li>Multiple </li>
			<li>Filters<ul>
				<li>Extensible filters</li>
			</ul>
			</li>
			<li>Independent horizontal and vertical <strong>flipping</strong></li>
			<li>Independent <strong>scaling</strong> of all three inputs</li>
			<li>Clipping</li>
			<li>Independent <strong>rotation</strong> of all three inputs (multiples of 90 degrees)</li>
		</ul>
		</td>
		<td style="width: 50%" valign="top">
		<ul>
			<li>Choice of <strong>scaling</strong> type<ul>
				<li>Quality based choice</li>
				<li>Speed based choice</li>
				<li>Image type based choice</li>
				<li>Specific scale type choice</li>
				<li>Extensible scale type</li>
			</ul>
			</li>
			<li>Synchronous operations</li>
			<li>Asynchronous operations<ul>
				<li>Client notification of BLT completion</li>
			</ul>
			</li>
			<li>Batching<ul>
				<li>Combine multiple BLTs into group that can be handled more efficiently by implementations<ul>
					<li>Character BLTs</li>
					<li>Multi-layer blending</li>
					<li>ROP/Blend combination with specified ordering</li>
					<li>etc.</li>
				</ul>
				</li>
				<li>Delta BLTs</li>
			</ul>
			</li>
			<li>Dithering<ul>
				<li>Quality based choice</li>
				<li>Speed based choice</li>
				<li>Image type based choice</li>
				<li>Specific dither type choice</li>
				<li>Extensible dither type</li>
			</ul>
			</li>
			<li>Any implementation support<ul>
				<li>CPU</li>
				<li>2-D Accelerator</li>
			</ul>
			</li>
		</ul>
		</td>
	</tr>
</table>
<hr />
<ul>
	<li>BLTsville does not dictate capabilities of the implementations<ul>
		<li>Operations specified either work or return an error indicating that the operation is not supported</li>
	</ul>
	</li>
</ul>
<hr />
<p class="Header1">How to Get to BLTsville</p>
<p>BLTsville&#39;s API is defined in the BLTsville header files.&nbsp; A client must include <span class="inline_code">bltsville.h</span> 
to access the implementations.&nbsp; This header includes the remaining headers (including <span class="inline_code">ocd.h</span>).</p>
<p class="note">NOTE:&nbsp; The <span class="underline_code">bvinternal.h</span><span class="underline"> header is for implementations 
only</span> and should not be used by clients.</p>
<p>BLTsville has both user mode and a kernel mode interaces.&nbsp; The kernel mode interface is quite similar to (and compatible 
with) the user mode, but due to the minor differences and license issues, there are two different sets of header files.</p>
<hr />
<p class="Header1">History of BLTsville</p>
<br />
<p class="Header4">Versions 1.x</p>
<p>BLTsville was based on a previous closed interface, which had a few implementations and shipped on a few devices.&nbsp; 
That interface represented the 1.x versions.&nbsp; A lot was learned from that work, and these lessons were used in the 
founding of BLTsville.</p>
<p class="Header4">Version 2.0</p>
<p>This was the initial release of the user mode interface.&nbsp; This version is not compatible with the 1.x versions.&nbsp; 
Several minor updates were posted, but the API itself did not change, so no changes to the client or implementation were 
required.</p>
<p class="Header4">Version 2.1</p>
<p>This is a minor update to the API, and it adds the kernel mode interface.&nbsp; Some additions to the API have been made.&nbsp; 
Details of the changes are below with their compatibility matrices.</p>
<ul>
	<li><span class="inline_code"><a href="#bv_cache">bv_cache()</a></span> was added to allow manipulation of the CPU cache.&nbsp; 
	This is an optional interface meant for hardware implementations.</li>
</ul>
<table class="indent_thin_bord">
	<tr>
		<td class="thin_bord">&nbsp;</td>
		<td class="ctr_thin_bord"><strong>2.0 Client</strong></td>
		<td class="ctr_thin_bord"><strong>2.0 Client</strong><br />
		(w/2.1 Headers)</td>
		<td class="ctr_thin_bord"><strong>2.1 Client</strong></td>
	</tr>
	<tr>
		<td class="thin_bord"><strong>2.0 Implementation</strong></td>
		<td class="ctr_thin_bord">compatible</td>
		<td class="ctr_thin_bord">New function and structure definitions have no effect.</td>
		<td class="ctr_thin_bord">Client must deal with lack of <span class="inline_code"><a href="#bv_cache">bv_cache()</a></span>.</td>
	</tr>
	<tr>
		<td class="thin_bord"><strong>2.0 Implementation</strong><br />
		(w/2.1 Headers)</td>
		<td class="ctr_thin_bord">New function and structure definitions have no effect.</td>
		<td class="ctr_thin_bord">New function and structure definitions have no effect.</td>
		<td class="ctr_thin_bord">Client must deal with lack of <span class="inline_code"><a href="#bv_cache">bv_cache()</a></span>.</td>
	</tr>
	<tr>
		<td class="thin_bord"><strong>2.1 Implementation</strong></td>
		<td class="ctr_thin_bord">New function and structures have no effect.</td>
		<td class="ctr_thin_bord">New function and structures have no effect.</td>
		<td class="ctr_thin_bord">compatible</td>
	</tr>
</table>
<ul>
	<li><span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> was extended with the
	<span class="inline_code"><a href="#bvbuffdesc.auxtype">auxtype</a></span> and <span class="inline_code">
	<a href="#bvbuffdesc.auxptr">auxptr</a></span> members to allow buffer descriptions beyond a virtual address.&nbsp; 
	Note that only the kernel mode interface currently includes a standard <span class="inline_code">auxtype</span>, but 
	user mode interface <span class="inline_code">auxtype</span>s may be added later.&nbsp; Both interfaces provide a mechanism 
	for individual vendors to add their own <span class="inline_code">auxtype</span>, using the same vendor ID mechanism 
	as the rest of BLTsville.</li>
</ul>
<table class="indent_thin_bord">
	<tr>
		<td class="thin_bord">&nbsp;</td>
		<td class="ctr_thin_bord"><strong>2.0 Client</strong></td>
		<td class="ctr_thin_bord"><strong>2.0 Client</strong><br />
		(w/2.1 Headers)</td>
		<td class="ctr_thin_bord"><strong>2.1 Client</strong></td>
	</tr>
	<tr>
		<td class="thin_bord"><strong>2.0 Implementation</strong></td>
		<td class="ctr_thin_bord">compatible</td>
		<td class="ctr_thin_bord">Client must clear <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> 
		using <span class="inline_code"><span style="white-space: nowrap">sizeof(<a href="#bvbuffdesc">bvbuffdesc</a>)</span></span>.</td>
		<td class="ctr_thin_bord">Implementation must handle <span class="inline_code">
		<a href="#bvbuffdesc.structsize">bvbuffdesc.structsize</a> &gt; <span style="white-space: nowrap">sizeof(<a href="#bvbuffdesc">bvbuffdesc</a>)</span></span>.</td>
	</tr>
	<tr>
		<td class="thin_bord"><strong>2.0 Implementation</strong><br />
		(w/2.1 Headers)</td>
		<td class="ctr_thin_bord">Implementation must handle <span class="inline_code">
		<a href="#bvbuffdesc.structsize">bvbuffdesc.structsize</a> &lt; <span style="white-space: nowrap">sizeof(<a href="#bvbuffdesc">bvbuffdesc</a>)</span></span>.</td>
		<td class="ctr_thin_bord">Client must clear <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> 
		using <span class="inline_code"><span style="white-space: nowrap">sizeof(<a href="#bvbuffdesc">bvbuffdesc</a>)</span></span>.</td>
		<td class="ctr_thin_bord">Client must deal with implementation that uses <span class="inline_code">
		<a href="#bvbuffdesc.virtaddr">bvbuffdesc.virtaddr</a></span> or returns error if <span class="inline_code">
		<a href="#bvbuffdesc.virtaddr">bvbuffdesc.virtaddr</a></span> is 0.</td>
	</tr>
	<tr>
		<td class="thin_bord"><strong>2.1 Implementation</strong></td>
		<td class="ctr_thin_bord">Implementation must handle <span class="inline_code">
		<a href="#bvbuffdesc.structsize">bvbuffdesc.structsize</a> &lt; <span style="white-space: nowrap">sizeof(<a href="#bvbuffdesc">bvbuffdesc</a>)</span></span>.</td>
		<td class="ctr_thin_bord">Client must clear <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> 
		using <span class="inline_code"><span style="white-space: nowrap">sizeof(<a href="#bvbuffdesc">bvbuffdesc</a>)</span></span>.</td>
		<td class="ctr_thin_bord">compatible</td>
	</tr>
</table>
<ul>
	<li>Added documentation of <a href="#NOP">NOP BLT</a> used as synchronization mechanism for <a href="#BVFLAG_ASYNC">
	asynchronous BLTs</a>.<ul>
		<li>Clients that do not use <a href="#BVFLAG_ASYNC">asynchronous BLTs</a> or the <a href="#NOP">NOP BLT</a> will 
		not be affected.</li>
		<li>Implementations that do not support the NOP BLT will return an error.&nbsp; This will not cause a problem 
		for clients when using implementations which are actually synchronous.&nbsp; For clients using asynchronous 
		implementations, an alternate supported but innocuous BLT will be necessary (e.g. copying a pixel to itself).</li>
	</ul>
	</li>
</ul>
<p class="Header4">Version 2.2</p>
<p>This is a minor update which includes the following:</p>
<ul>
	<li>Addition of the <span class="inline_code"><a href="#src2auxdstrect">src2auxdstrect</a></span> and
	<span class="inline_code"><a href="#maskauxdstrect">maskauxdstrect</a></span> members to <span class="inline_code">
	<a href="#bvbltparams">bvbltparams</a></span> with example.</li>
	<li>Addition of <span class="inline_code"><a href="#BVFLAG_SRC2_AUXDSTRECT">BVFLAG_SRC2_AUXDSTRECT</a></span> and <span class="inline_code">
	<a href="#BVFLAG_MASK_AUXDSTRECT">BVFLAG_MASK_AUXDSTRECT</a></span> flags.</li>
	<li>Added <span class="inline_code"><a href="#BVAT_PHYSADDR">BVAT_PHYSADDR</a></span> to the kernel mode
	<span class="inline_code"><a href="#bvbuffdesc.auxtype">bvbuffdesc.auxtype</a></span> enumerations.</li>
	<li>Added clarification to the <span class="inline_code"><a href="#bvphysdesc">bvphysdesc</a></span> documentation.</li>
</ul>
<p>Compatibility</p>
<ul>
	<li>Clients that do not use the <span class="inline_code"><a href="#BVFLAG_SRC1_AUXDSTRECT">BVFLAG_*_AUXDSTRECT</a></span> 
	flags will not be affected.</li>
	<li>Clients using the new (long) <span class="inline_code"><a href="#bvbltparams">bvbltparams</a></span> will work with 
	older implementations.&nbsp; If the clients set the <span class="inline_code"><a href="#BVFLAG_SRC2_AUXDSTRECT">
	BVFLAG_*_AUXDSTRECT</a></span> flags, the implementations will return <span class="inline_code">BVERR_FLAGS</span>, 
	indicating the lack of support for this feature.</li>
	<li>Implementations supporting the new <span class="inline_code"><a href="#bvbltparams">bvbltparams</a></span> will 
	accept the older (smaller) version, distinguished by the <span class="inline_code">
	<a href="#bvbltparams.structsize">structsize</a></span> member.&nbsp; Clients using the older versions will not set 
	the <span class="inline_code"><a href="#BVFLAG_SRC2_AUXDSTRECT">BVFLAG_*_AUXDSTRECT</a></span> flags, so the new 
	members will not be utilized.</li>
	<li>Clients using <span class="inline_code"><a href="#BVAT_PHYSADDR">BVAT_PHYSADDR</a></span> will get an error from 
	implementations that do not support this enumeration.&nbsp; The <span class="inline_code"><a href="#BVAT_PHYSDESC">
	BVAT_PHYSDESC</a></span> may be used if supported by the implementation, but care must be taken to ensure the buffer 
	is defined properly.&nbsp; See <span class="inline_code"><a href="#bvphysdesc">bvphysdesc</a></span> for details.</li>
</ul>
<hr />
<p class="Header1">BLTsville Neighborhoods</p>
<p>Implementations may be software (CPU) or 2-D hardware, and many may coexist.&nbsp; Each implementation will have an individual 
entry point, so it can be directly addressed.&nbsp; But there will also be a more general interface for each of these two 
types of implementations so that system integrators can choose the most appropriate implementation.&nbsp; In other words, 
the system integrator will choose one software and one 2-D hardware implementation to be the &quot;default&quot; used when a client 
does not need to choose a specific implementation.</p>
<p class="Header2">User Mode Interface</p>
<p>Clients use the standard names below to access the default implementations.&nbsp; The client then imports the pointers 
to the functions.&nbsp; (The specific name decoration and import method will be dictated by the host Operating System (O/S).)&nbsp; 
Some examples:</p>
<ul>
	<li>CPU:&nbsp; <span class="filename">bltsville_cpu</span><ul>
		<li>Linux/Android:&nbsp; <span class="filename">libbltsville_cpu.so</span></li>
		<li>Windows:&nbsp; <span class="filename">bltsville_cpu.dll</span></li>
		<li>etc.</li>
	</ul>
	</li>
	<li>2-D hardware:&nbsp; <span class="filename">bltsville_hw2d</span><ul>
		<li>Linux/Android:&nbsp; <span class="filename">libbltsville_hw2d.so</span></li>
		<li>Windows:&nbsp; <span class="filename">bltsville_hw2d.dll</span></li>
		<li>etc.</li>
	</ul>
	</li>
</ul>
<p>Usually these entry points will be symbolic links (either explicit in systems like Linux which support them, or implicit 
using a thin wrapper) to the specific implementation.&nbsp; This allows system integrators to connect the client with the 
most capable implementation available in the system.&nbsp; For example, <span class="filename">bltsville_hw2d</span> might 
be a symbolic link to <span class="filename">bltsville_gc2d</span>.</p>
<p>In addition, there may be more implementations co-existing in a given system.&nbsp; These will have additional unique 
names as determined by the vendors.&nbsp; For example:</p>
<ul>
	<li>Reference CPU software implementation:&nbsp; <span class="filename">bltsville_refcpu</span></li>
	<li>System DMA 2-D hardware implementation:&nbsp; <span class="filename">bltsville_mydma</span></li>
</ul>
<p class="Header3">Initialization</p>
<p>In general, each O/S has the ability to manually load a library.&nbsp; This in turn causes a function in the library 
to be called so the library can perform initialization.&nbsp; Unfortunately, not all O/Ss allow this initialization 
function to return an error if the initialization fails.&nbsp; Equally unfortunately, it may be necessary for the 
initialization to be performed in that function.&nbsp; To accommodate this, BLTsville defers the specific initialization 
to the O/S environment.</p>
<p class="Header4">Linux/Android</p>
<p>The client will call <span class="inline_code">dlopen()</span> to open the library.&nbsp; It will then import the
<span class="inline_code">bv_*()</span> functions, and call them as desired.&nbsp; Initialization will occur in 
association with one or more of these activities.&nbsp; If the initialization fails, the bv_*() functions will return 
the <span class="inline_code">BVERR_RSRC</span> error, indicating that a required resource was not obtained.</p>
<p class="imponly"><strong>Implementations Only<br />
</strong><br />
If the library has designated a function with the <span class="inline_code">__attribute__ ((constructor))</span>, that 
function will be called.&nbsp; Linux implementations may use this function to perform initialization (including opening 
an interface to an associated kernel module).&nbsp; However, since this function cannot return an error, and thus cannot 
fail, if the initialization fails, this must be recorded.&nbsp; Then, when the client calls any of the
<span class="inline_code">bv_*()</span> functions, these should immediately return the <span class="inline_code">
BVERR_RSRC</span> error, indicating that the library was unable to initialize (obtain a necessary resource).<br />
<br />
Linux implementations may also choose to initialize on the first call to a <span class="inline_code">bv_*()</span> 
function.&nbsp; Failure is likewise indicated by returning the <span class="inline_code">BVERR_RSRC</span> error.<br />
<br />
<strong>NOTE:&nbsp; Be careful not to repeatedly attempt initialization when a failure is encountered.&nbsp; Some 
initializations, and especially initialization failures, can take a long time.&nbsp; This means clients trying to call
</strong><span class="inline_code"><strong>bv_*()</strong></span><strong> functions (presumably before falling back to 
alternatives) will be repeatedly penalized if the library can&#39;t initialize.&nbsp; Instead, attempt initialization 
once, and from them on return <span class="inline_code">BVERR_RSRC</span>.</strong></p>
<p class="Header2">Kernel Mode Interface</p>
<p>For most kernel space BLTsville clients, only a 2-D hardware implementation will be used.&nbsp; However, both types of 
implementations are supported.&nbsp; Clients use the standard names below to access the default implementations and obtain 
pointers to the functions.&nbsp; (The specific method of obtaining the interface will be dictated by the host Operating 
System (O/S).)&nbsp; Some examples:</p>
<ul>
	<li>CPU<ul>
		<li>Linux/Android <span class="inline_code">bvcpu_entry()</span></li>
		<li>etc.</li>
	</ul>
	</li>
	<li>2-D hardware<ul>
		<li>Linux/Android <span class="inline_code">bv2d_entry()</span></li>
		<li>etc.</li>
	</ul>
	</li>
</ul>
<p>These entry points may represent the implementations themselves, but more likely they will link the client to the implementations 
using more specific names.&nbsp; For example, <span class="inline_code">bv2d_entry()</span> may link the client to
<span class="inline_code">gcbv_entry()</span>.</p>
<p>In addition, there may be more implementations co-existing in the kernel.&nbsp; These will require additional unique 
names as determined by the vendors.&nbsp; For example:</p>
<ul>
	<li>Reference CPU software implementation:&nbsp; <span class="inline_code">cpurefbv_entry()</span></li>
	<li>Vivante GC320 2-D hardware implementation:&nbsp; <span class="inline_code">gcbv_entry()</span></li>
</ul>
<hr />
<p class="Header1">Things To Do In BLTsville</p>
<p>BLTsville&#39;s interface consists of three or four functions per implementation, which must be imported by the 
client at run time:</p>
<ul>
	<li><span class="inline_code"><a href="#bv_map">bv_map()</a></span></li>
	<li><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></li>
	<li><span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span></li>
	<li><span class="inline_code"><a href="#bv_cache">bv_cache()</a></span> (optional)</li>
</ul>
<p class="note">NOTE:&nbsp; If the library failed to initialize, these functions will return <span class="inline_code">
BVERR_RSRC</span>, indicating that a required resource was not obtained.</p>
<a name="bv_map" class="Code_Header">bv_map()</a>
<p class="code_block">enum bverror bv_map(<a href="#bvbuffdesc">struct bvbuffdesc* buffdesc</a>);</p>
<p><span class="strong_emphasis">BLTsville does not allocate buffers.</span>&nbsp;&nbsp; Clients must describe a buffer 
in BLTsville using the <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> structure so a given implementation 
can access the buffer.</p>
<p><span class="inline_code">bv_map()</span> is used to provide the implementation an opportunity to associate hardware 
resources with the specified buffer.&nbsp; Most hardware requires this type of mapping, and there is usually appreciable 
overhead associated with it.&nbsp; By providing a separate call for this operation, BLTsville allows the client to move 
this overhead to the most appropriate time in its execution.</p>
<p>For a given buffer, the client can call the <span class="inline_code">bv_map()</span> function imported from each implementation 
to establish the mapping immediately.&nbsp; But this is not required.</p>
<p>As a special bonus, BLTsville clients can call to any implementation&#39;s <span class="inline_code">bv_map()</span>.&nbsp; 
This is sufficient to indicate that the client can be trusted to make the corresponding call to
<span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span> upon destruction of the buffer.&nbsp; Then when a client 
calls an implementation&#39;s <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span>, if the mapping needs to be done, 
it&#39;s done at that time.&nbsp; But the mapping is maintained, so that the overhead is avoided on subsequent
<span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> calls.&nbsp; This lets implementations use <em>lazy mapping</em> 
only as necessary.&nbsp; If an implementation is not called, the mapping is not done.</p>
<p><em>Normally, the lowest overhead </em><span class="inline_code"><em>bv_map()</em></span><em> call will be in the CPU-based 
implementation.&nbsp; So most clients will want to make a single, low overhead </em><span class="inline_code"><em>bv_map()</em></span><em> 
call to the bltsville_cpu implementation to avoid the mapping/unmapping overhead on each </em><span class="inline_code">
<a href="#bv_blt"><em>bv_blt()</em></a></span><em> call, while avoiding the mapping overhead when possible.</em></p>
<p><em><strong>Calling </strong></em><span class="inline_code"><em><strong>bv_map()</strong></em></span><em><strong> is 
actually optional prior to calling </strong></em><span class="inline_code"><a href="#bv_blt"><em><strong>bv_blt()</strong></em></a></span><em><strong>.&nbsp; 
However, if it is not called at least once for a given buffer, it must be assumed that </strong></em>
<span class="inline_code"><a href="#bv_unmap"><strong><em>bv_unmap()</em></strong></a></span><em><strong> will not be called.&nbsp; 
So the mapping must be done when </strong></em><span class="inline_code"><a href="#bv_blt"><em><strong>bv_blt()</strong></em></a></span><em><strong> 
is called, and unmapping done when it is complete.&nbsp; This means the overhead will be incurred for every </strong>
</em><a href="#bv_blt" class="inline_code"><em><strong>bv_blt()</strong></em></a><em><strong> call which uses that buffer.</strong></em></p>
<p class="note">NOTE: Obviously any API cannot add capabilities beyond an implementation&#39;s capabilities.&nbsp; So, for example, 
if an implementation requires memory to be allocated from a special pool of memory, that responsibility falls upon the client.&nbsp; 
The <span class="inline_code">bv_map()</span> function for that implementation will need to check the characteristics of 
the memory and return an error if it does not meet the necessary criteria.</p>
<p class="Header4"><a name="bv_map_Function_Sequences">Function Sequences</a></p>
<p>To clarify, here are some function sequences and the operations associated with them:</p>
<table class="indent">
	<tr>
		<td class="ctr_thin_bord"><strong>Implementation</strong></td>
		<td class="ctr_thin_bord"><strong>Function</strong></td>
		<td class="ctr_thin_bord"><strong>Operation</strong></td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">A</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
		<td class="thin_bord">map A<br />
		BLT A<br />
		unmap A</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">A</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
		<td class="thin_bord">map A<br />
		BLT A<br />
		unmap A</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">B</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
		<td class="thin_bord">map B<br />
		BLT B<br />
		unmap B</td>
	</tr>
</table>
<br />
<table class="indent">
	<tr>
		<td class="ctr_thin_bord"><strong>Implementation</strong></td>
		<td class="ctr_thin_bord"><strong>Function</strong></td>
		<td class="ctr_thin_bord"><strong>Operation</strong></td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">A</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_map">bv_map()</a></span></td>
		<td class="thin_bord">map A</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">A</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
		<td class="thin_bord">BLT A</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">A</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
		<td class="thin_bord">BLT A</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">A</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span></td>
		<td class="thin_bord">unmap A</td>
	</tr>
</table>
<br />
<table class="indent">
	<tr>
		<td class="ctr_thin_bord"><strong>Implementation</strong></td>
		<td class="ctr_thin_bord"><strong>Function</strong></td>
		<td class="ctr_thin_bord"><strong>Operation</strong></td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">A</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_map">bv_map()</a></span></td>
		<td class="thin_bord">map A</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">B</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_map">bv_map()</a></span></td>
		<td class="thin_bord">map B</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">A</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
		<td class="thin_bord">BLT A</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">B</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
		<td class="thin_bord">BLT B</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">A</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span></td>
		<td class="thin_bord">unmap A</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">B</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span></td>
		<td class="thin_bord">unmap B</td>
	</tr>
</table>
<br />
<table class="indent">
	<tr>
		<td class="ctr_thin_bord"><strong>Implementation</strong></td>
		<td class="ctr_thin_bord"><strong>Function</strong></td>
		<td class="ctr_thin_bord"><strong>Operation</strong></td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">A</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_map">bv_map()</a></span></td>
		<td class="thin_bord">map A</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">B</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
		<td class="thin_bord">map B<br />
		BLT B</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">B</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
		<td class="thin_bord">BLT B</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">A</td>
		<td class="thin_bord"><span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span></td>
		<td class="thin_bord">unmap A<br />
		unmap B</td>
	</tr>
</table>
<br />
<div class="note">
	NOTE:&nbsp; Calling <span class="inline_code">bv_map()</span> and <span class="inline_code"><a href="#bv_unmap">
	bv_unmap()</a></span> with the same <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> from 
	different, unsynchronized threads, even (especially) from different implementations, will result in undefined 
	behavior.&nbsp; This is similar to calling <span class="inline_code">malloc()</span> and <span class="inline_code">
	free()</span> using the same buffer pointer in different, unsynchronized threads.&nbsp; While this may work 
	sometimes and for some implementations and combinations of implementations, BLTsville does not provide any 
	synchronization mechanism to make this safe.&nbsp; Clients must ensure that these calls are synchronized in cases 
	where such behavior appears to be necessary.</div>
<br />
<a name="bv_blt" class="Code_Header">bv_blt()</a>
<p class="code_block">enum bverror bv_blt(<a href="#bvbltparams">struct bvbltparams* bltparams</a>);</p>
<p>The main function of BLTsville is <span class="inline_code">bv_blt()</span>.&nbsp; A <span class="inline_code">
<a href="#bvbltparams">bvbltparams</a></span> structure is passed into <span class="inline_code">bv_blt()</span> to trigger 
the desired 2-D operation.</p>
<a name="bv_unmap" class="Code_Header">bv_unmap()</a>
<p class="code_block">enum bverror bv_unmap(<a href="#bvbuffdesc">struct bvbuffdesc* buffdesc</a>);</p>
<p><span class="inline_code">bv_unmap()</span> is used to free implementation resources associated with a buffer.&nbsp; 
Normally, if <span class="inline_code"><a href="#bv_map">bv_map()</a></span> was called for a given buffer,
<span class="inline_code">bv_unmap()</span> should be called as well.</p>
<p>For convenience, only one <span class="inline_code">bv_unmap()</span> needs to be called for each buffer, regardless 
of how many implementations were used, including multiple calls to <span class="inline_code"><a href="#bv_map">bv_map()</a></span>.</p>
<p>Also for convenience, <span class="inline_code">bv_unmap()</span> may be called multiple times on the same buffer.&nbsp; 
Note that only the first call will actually free (all) the associated resources.&nbsp; See the
<a href="#bv_map_Function_Sequences">Function Sequences</a> under <span class="inline_code"><a href="#bv_map">bv_map()</a></span> 
for more details.</p>
<p class="imponly"><strong>Implementations Only</strong><br />
<br />
Implementations must ensure that unmapping of buffers which are in use by asynchronous BLTs are appropriately delayed to 
avoid improper access.</p>
<a name="bv_cache" class="Code_Header">bv_cache()</a>
<p class="code_block">enum bverror bv_cache(<a href="#bvcopprams">struct bvcopparams *copparams</a>);</p>
<p><span class="inline_code">bv_cache()</span> provides manual CPU cache control to maintain cache coherence of surfaces 
between the CPU and other hardware.&nbsp; The <a href="#bvbuffdesc">bvcopparams</a> structure provides the information needed 
to properly manipulate the CPU cache.</p>
<p>This function is <em>optional</em>.&nbsp; If this function fails to import, it means the implementation does not provide 
it, but <span class="inline_code"><a href="#bv_map">bv_map()</a></span>,&nbsp; <span class="inline_code">
<a href="#bv_blt">bv_blt()</a></span>, and <span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span> may still 
be used.</p>
<p><em>In general, this function will be provided with BLTsville implementations which utilize 2-D hardware, even though 
it manipulates the CPU cache.&nbsp; This is because most systems require a kernel module to manipulate the cache, and this 
is not always practical to include with a user-mode CPU implementation.</em></p>
<p><strong>BEWARE:&nbsp; Manipulation of the CPU cache is tricky.&nbsp; Moreover, different CPUs behave differently, so 
cache manipulation that works on one device may fail on another.&nbsp; Also, mismanaged operation of the cache can have 
significant impact on overall system performance.&nbsp; And incorrect manipulation of the cache can cause instability or 
crashes.&nbsp; Please read and understand all of the discussions below before using this function.</strong></p>
<ol>
	<li>To avoid system instability, do not perform cache operations on buffers which would not be accessed by BLTsville.</li>
	<li>For maximum performance, combine adjacent rectangles into one <span class="inline_code">bv_cache()</span> call.&nbsp; 
	For example, when BLTing a line of characters, do not issue a <span class="inline_code">bv_cache()</span> call for each 
	character.&nbsp; Instead, make one call to bv_cache() which includes all the characters.</li>
	<li>When using a hardware BLTsville implementation to read data written into a cached surface by the CPU, use the
	<span class="inline_code"><a href="#CPU_TO_DEVICE">BVCACHE_CPU_TO_DEVICE</a></span> operation after the CPU has completed 
	its operation and before the hardware BLTsville operation is initiated.</li>
	<li>When using a hardware BLTsville implementation to write data into a cached surface that will be read by the CPU, 
	use the <span class="inline_code"><a href="#CPU_FROM_DEVICE">BVCACHE_CPU_FROM_DEVICE</a></span> operation after the 
	hardware BLTsville operation has completed (note this means after the callback if the BLT is asynchronous) and before 
	the CPU accesses the surface.</li>
	<li>When using a hardware BLTsville implementation to write data into a cached surface that has been written by the 
	CPU, using the <span class="inline_code"><a href="#CPU_TO_DEVICE">BVCACHE_CPU_TO_DEVICE</a></span> operation after the 
	CPU has completed its operation and before the hardware BLTsville operation is initiated.<ul>
		<li class="bold_sans">NOTE:&nbsp; This cache operation may not be necessary on all hardware, but it is good practice to perform it 
		anyway.&nbsp; This operation will be necessary for a CPU with a write allocation policy on the cache, but may not 
		be necessary for CPUs without such a configuration.</li>
		<li class="bold_sans"><strong>NOTE WELL:&nbsp; CPU access to a destination buffer is not always initiated by the client.&nbsp; Buffers 
		recently allocated may be cleared by the CPU on behalf of the client via the allocation call.&nbsp; Failure to perform 
		this operation may result in image corruption even if no further CPU accesses are performed on the surface!</strong></li>
	</ul>
	</li>
</ol>
<table class="example">
	<tr>
		<td>
		<p><strong>Example</strong>:&nbsp; On one particular device, a surface was allocated using the standard user mode
		<span class="inline_code">malloc()</span>.&nbsp; An image was copied into a portion of this surface using a hardware 
		implementation of BLTsville.&nbsp; The result was then read by the CPU.</p>
		<p>Logically, <span class="inline_code">bv_cache()</span> was used to perform a <span class="inline_code">
		<a href="#CPU_FROM_DEVICE">BVCACHE_CPU_FROM_DEVICE</a></span> operation after the hardware-based BLTsville operation 
		completed, but before the CPU read was performed.&nbsp; However, corruption appeared both inside the image copied, 
		as well as outside the image!</p>
		<p>Both corruptions were caused by not realizing that there was a CPU operation (clear) performed on behalf of the
		<span class="inline_code">malloc()</span>, for which the proper cache manipulation was not performed.</p>
		<p>The corruption outside the image was due to data in the cache being invalidated before it reached the memory.&nbsp; 
		As mentioned above, buffers allocated are normally cleared by the system.&nbsp; In this case, since the buffer used 
		for the surface was configured with a write allocated cache, this meant that not all writes to clear the buffer 
		were in memory when the&nbsp; <span class="inline_code"><a href="#CPU_FROM_DEVICE">BVCACHE_CPU_FROM_DEVICE</a></span> 
		operation was performed.&nbsp; As a result, the uncommitted data in the cache was invalidated and lost, and the 
		previous contents of the memory remained for the CPU to read.</p>
		<p>The corruption inside the image was caused by data in the cache being committed to memory after the hardware 
		BLT completed, but before the <span class="inline_code"><a href="#CPU_FROM_DEVICE">BVCACHE_CPU_FROM_DEVICE</a></span> 
		operation was executed.</p>
		<p>Both corruptions were corrected by performing a <span class="inline_code"><a href="#CPU_TO_DEVICE">BVCACHE_CPU_TO_DEVICE</a></span> 
		operation on the <span class="underline">destination</span> surface <strong>before</strong> performing the BLT (item 
		5 above), in addition to the <span class="inline_code"><a href="#CPU_FROM_DEVICE">BVCACHE_CPU_FROM_DEVICE</a></span> 
		operation performed <strong>after</strong> the BLT (item 3 above).</p>
		</td>
	</tr>
</table>
<br />
<hr /><a name="bvbltparams" class="Code_Header">bvbltparams</a>
<p><span class="inline_code">bvbltparams</span> is the central structure in BLTsville.&nbsp; This structure holds the details 
of the BLT being requested by the client.</p>
<p class="small_code_block">union bvop {<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned short <a href="#rop">rop</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; enum bvblend <a href="#blend">blend</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct bvfilter *<a href="#filter">filter</a>;<br />
};<br />
<br />
struct bvinbuff {<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvbuffdesc">struct bvbuffdesc</a> *<a href="#src1.desc">desc</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvtileparams">struct bvtileparams</a> *<a href="#src1.tileparams">tileparams</a>;<br />
};<br />
<br />
struct bvbltparams {<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned int <a href="#bvbltparams.structsize">structsize</a>;<br />
<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; char *<a href="#errdesc">errdesc</a>;<br />
<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned long <a href="#implementation">implementation</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned long <a href="#flags">flags</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; union bvop <a href="#op">op</a>;<br />
<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *<a href="#colorkey">colorkey</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; union bvalpha <a href="#globalalpha">globalalpha</a>;<br />
<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; enum bvscalemode <a href="#scalemode">scalemode</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; enum bvdithermode <a href="#dithermode">dithermode</a>;<br />
<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvbuffdesc">struct bvbuffdesc</a> *<a href="#dstdesc">dstdesc</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvsurfgeom">struct bvsurfgeom</a> *<a href="#dstgeom">dstgeom</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvrect">struct bvrect</a> <a href="#dstrect">dstrect</a>;<br />
<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; union bvinbuff <a href="#src1">src1</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvsurfgeom">struct bvsurfgeom</a> *<a href="#src1geom">src1geom</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvrect">struct bvrect</a> <a href="#src1rect">src1rect</a>;<br />
<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; union bvinbuff <a href="#src2">src2</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvsurfgeom">struct bvsurfgeom</a> *<a href="#src2geom">src2geom</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvrect">struct bvrect</a> <a href="#src2rect">src2rect</a>;<br />
<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; union bvinbuff <a href="#mask">mask</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvsurfgeom">struct bvsurfgeom</a> *<a href="#maskgeom">maskgeom</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvrect">struct bvrect</a> <a href="#maskrect">maskrect</a>;<br />
<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvrect">struct bvrect</a> <a href="#cliprect">cliprect</a>;<br />
<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned long <a href="#batchflags">batchflags</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct bvbatch *<a href="#batch">batch</a>;<br />
<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void (*<a href="#callbackfn">callbackfn</a>)(<a href="#bvcallbackerror">struct 
bvcallbackerror</a> *err,<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
unsigned long callbackdata);<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned long <a href="#callbackdata">callbackdata</a>;<br />
<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvrect">struct bvrect</a> <a href="#src2auxdstrect">src2auxdstrect</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvrect">struct bvrect</a> <a href="#maskauxdstrect">maskauxdstrect</a>;<br />
};</p>
<a name="bvbltparams.structsize" class="Code_Header_2">bvbltparams.structsize</a>
<p><span class="code_block">unsigned long structsize; /* input */</span></p>
<p>This member is used to allow backwards and forwards compatibility between versions of BLTsville.&nbsp; It should be set 
to the <span class="inline_code">sizeof()</span> the structure by the client or implementation, whichever allocated the 
structure.</p>
<p>BLTsville is designed to be forwards and backwards compatible between client and library versions.&nbsp; But this compatibility 
would be eliminated if clients chose to check for a specific version of the BLTsville implementations and fail if the specific 
version requested was not in place.&nbsp; So, instead of exporting a version number, BLTsville structures use the
<span class="inline_code">structsize</span> member to indicate the number of bytes in the structure.&nbsp; This is used 
to communicate between the client and implementation which portions of the structure exist.&nbsp; This effectively bypasses 
the concept of a version and focuses on the specifics of what changes need to be considered to maintain compatibility.</p>
<ol>
	<li>When an old client calls into a new implementation, that implementation will realize if the client only provides 
	a subset of an updated structure.&nbsp; The implementation will handle this and utilize only that information which 
	has been provided.&nbsp; New features will be disabled, but functionality will be maintained.</li>
	<li>When a new client calls into an old implementation, that implementation will ignore the extra members of the structure 
	and operate in ignorance of them.&nbsp; If these members are necessary for some new functionality, this will be evident 
	from other fields in the structure, so that the implementation can gracefully fail.</li>
</ol>
<p>If <span class="inline_code">structsize</span> is set to a value that is too small for an implementation, it may return 
a <span class="inline_code"><a href="#BVERR_BLTPARAMS_VERS">BVERR_BLTPARAMS_VERS</a></span> error.</p>
<p class="Code_Header_2"><a name="bvbltparams.errdesc">bvbltparams.errdesc</a></p>
<p><span class="code_block">char* errdesc; /* output */</span></p>
<p><span class="inline_code">errdesc</span> is optionally used by implementations to pass a 0-terminated string with additional 
debugging information back to clients for debugging purposes.&nbsp; <span class="inline_code">errdesc</span> is not localized 
or otherwise meant to provide information that is displayed to users.</p>
<p class="Code_Header_2"><a name="implementation">bvbltparams.implementation</a></p>
<p class="code_block">unsigned long implementation; /* input */</p>
<p>Multiple implementations of BLTsville can be combined under managers which can distribute the BLT requests to the implementations 
based on whatever criteria the manager chooses.&nbsp; This might include availability of the operation, performance, loading, 
or power state.&nbsp; In such a scenario, the client may need to override or augment the choice made by the manager.&nbsp; 
This field allows that control.</p>
<p><strong><em>Note that this feature is extremely complicated, and more detailed documentation needs to be created to allow 
creation of managers and smooth integration by a client.&nbsp; There are serious issues that must be understood before any 
manager can be put into place, such as CPU cache coherence and multiple implementation operation interdependence.&nbsp; 
For now, this field should be set to 0 by clients.</em></strong></p>
<p>If the implementation cannot respond to the <span class="inline_code">implementation</span> flags set, it may return 
a <span class="inline_code"><a href="#BVERR_IMPLEMENTATION">BVERR_IMPLEMENTATION</a></span> error.</p>
<p class="Code_Header_2"><a name="flags">bvbltparams.flags</a></p>
<p class="code_block">unsigned long flags; /* input */</p>
<p>The <span class="inline_code">flags</span> member provides the baseline of information to <span class="inline_code">
<a href="#bv_blt">bv_blt()</a></span> about the type of BLT being requested.</p>
<p>To maintain compatibility, unused bits in the flags member should be set to 0.</p>
<p>If the flags set are not supported by the implementation, it may return <span class="inline_code">
<a href="#BVERR_FLAGS">BVERR_FLAGS</a></span>, or a more specific <a href="#bverror">error code</a>.</p>
<p class="Code_Header_3"><a name="BVFLAG_OP_">bvbltparams.flags - BVFLAG_OP_*</a></p>
<p>The <span class="inline_code">op</span> field of the flags member specifies the type of BLT operation to perform.&nbsp; 
Currently there are three types of BLT operations defined:</p>
<table class="indent">
	<tr>
		<td valign="top">1.</td>
		<td><span class="inline_code"><strong><a name="BVFLAG_ROP">BVFLAG_ROP</a></strong></span><br />
		<p>This flag indicates the operation being performed is a raster operation, and the <span class="inline_code">
		<a href="#op">bvbltparams.op</a></span> union is treated as <span class="inline_code"><a href="#rop">rop</a></span>.&nbsp; 
		Raster OPerations are binary operations performed on the bits of the inputs.&nbsp; See <span class="inline_code">
		<a href="#rop">bvbltparams.op.rop</a></span> for details.<br />
		<br />
		</p>
		</td>
	</tr>
	<tr>
		<td valign="top">2.</td>
		<td>
		<p><span class="inline_code"><strong><a name="BVFLAG_BLEND">BVFLAG_BLEND</a></strong></span><br />
		</p>
		<p>This flag indicates the operation being performed is a blend, and the <span class="inline_code">
		<a href="#op">bvbltparams.op</a></span> union is treated as <span class="inline_code"><a href="#blend">blend</a></span>.&nbsp; 
		Blending involves mixing multiple layers of pixels using the specified equations.&nbsp; Surrounding pixels are not 
		involved in blend operations.&nbsp; See <span class="inline_code"><a href="#blend">bvbltparams.op.blend</a></span> 
		for details.<br />
		<br />
		</p>
		</td>
	</tr>
	<tr>
		<td valign="top">3.</td>
		<td><span class="inline_code"><strong><a name="BVFLAG_FILTER">BVFLAG_FILTER</a></strong></span><br />
		<br />
		This flag indicates the operation being performed is a filter, and the <span class="inline_code"><a href="#op">bvbltparams.op</a></span> 
		union is treated as <span class="inline_code"><a href="#filter">filter</a></span>.&nbsp; Filtering involves mixing 
		multiple layers of pixels.&nbsp; Surrounding pixels are involved in filter operations.&nbsp; See
		<span class="inline_code"><a href="#filter">bvbltparams.op.filter</a></span> for details.<br />
		</td>
	</tr>
</table>
<p class="Code_Header_3"><a name="BVFLAG_KEY_SRC">bvbltparams.flags - BVFLAG_KEY_SRC</a>/<a name="BVFLAG_KEY_DST">DST</a></p>
<p>The <span class="inline_code">BVFLAG_KEY_SRC</span> and <span class="inline_code">BVFLAG_KEY_DST</span> enable source 
and destination color keying, respectively.&nbsp; When either flag is set, the <span class="inline_code">
<a href="#colorkey">colorkey</a></span> member of <span class="inline_code"><a href="#bvbltparams">bvbltparams</a></span> 
is used.</p>
<p><span class="inline_code">BVFLAG_KEY_SRC</span> and <span class="inline_code">BVFLAG_KEY_DST</span> are mutually exclusive.</p>
<p>See <span class="inline_code"><a href="#colorkey">bvbltparams.colorkey</a></span> for details.</p>
<p class="Code_Header_3"><a name="BVFLAG_CLIP">bvbltparams.flags - BVFLAG_CLIP</a></p>
<p>When <span class="inline_code">BVFLAG_CLIP</span> is set, the <span class="inline_code"><a href="#cliprect">cliprect</a></span> 
member of <span class="inline_code"><a href="#bvbltparams">bvbltparams</a></span> is used by the implementation as a limiting 
rectangle on data written to the destination.&nbsp; See <span class="inline_code"><a href="#cliprect">cliprect</a></span> 
for details.</p>
<p class="Code_Header_3"><a name="BVFLAG_SRCMASK">bvbltparams.flags - BVFLAG_SRCMASK</a></p>
<p>Normally, the mask is applied at the destination, after all scaling has been completed (including scaling the mask if 
necessary).&nbsp; But some environments require that the mask be applied at the sources, before scaling occurs.&nbsp; The
<span class="inline_code">BVFLAG_SRCMASK</span> flag requests that the implementation use this method if supported.</p>
<p class="Code_Header_3">bvbltparams.flags - BVFLAG_TILE_*</p>
<p>Normally, when a source&#39;s size does not match the destination, the source is scaled to fill the destination.&nbsp; But 
when the corresponding <span class="inline_code">BVFLAG_TILE_*</span> flag is set, this behavior is modified.</p>
<p>First, the source&#39;s size specifies a tile (or pattern, or brush) to be used to fill the destination.&nbsp; This tile 
is replicated instead of scaled.</p>
<p>The origin of the source&#39;s rectangle is used to locate the tile within a larger surface. </p>
<p>Second, a <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> object is no longer supplied by the client 
in the bvbltparams structure.&nbsp; In its place is a <span class="inline_code"><a href="#bvtileparams">bvtileparams</a></span> 
object.</p>
<p>Refer to the <span class="inline_code"><a href="#bvtileparams">bvtileparams</a></span> structure definition for details.</p>
<p class="Code_Header_3">bvbltparams.flags - <a name="BVFLAG_HORZ_FLIP">BVFLAG_HORZ</a>/<a name="BVFLAG_VERT_FLIP">VERT_FLIP_*</a></p>
<p>These flags indicate that the corresponding image is flipped horizontally or vertically as it is used by the operation.</p>
<p class="Code_Header_3">bvbltparams.flags - BVFLAG_SCALE/DITHER_RETURN</p>
<p>The scale and dither types can be specified with an implicit type.&nbsp; The implementation will then convert that internally 
to an explicit scale or dither type.&nbsp; These flags request that the implementation return the explicit type chosen to 
the client in the corresponding <span class="inline_code"><a href="#scalemode">bvbltparams.scalemode</a></span> and
<span class="inline_code"><a href="#dithermode">bvbltparams.dithermode</a></span> members.</p>
<p class="Code_Header_3">bvbltparams.flags - BVFLAG_ASYNC</p>
<p>This flag allows the client to inform the implementation that it can queue the requested BLT and return from
<span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> before it has completed.&nbsp; If this bit is not set, when 
the <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> returns, the operation is complete.</p>
<p>Normally, a client will also utilize the <span class="inline_code"><a href="#callbackfn">bvbltparams.callbackfn</a></span> 
and <span class="inline_code"><a href="#callbackdata">bvbltparams.callbackdata</a></span> members to receive a notification 
when the BLT has completed.</p>
<p class="note">NOTE:&nbsp; Asynchronous BLTs are performed in the order in which they are submitted within an implementation.&nbsp; 
This was done to provide a simple dependency mechanism.&nbsp; 
However, synchronization between implementations must be handled by the client, using the callback mechanism.</p>
<p class="note">NOTE:&nbsp; Since asynchronous BLTs are performed in the order in which they are submitted, it follows 
that a synchronized BLT after a set of asynchronous BLTs may be used as synchronization as well.</p>
<p class="note"><a name="NOP">NOTE</a>:&nbsp; Certain situations may require manual synchronization without an associated BLT.&nbsp; 
Rather than introduce an additional BLTsville function call, the method of handling this will be via a NOP BLT.&nbsp; To 
accomplish a NOP BLT, the client should issue a BLT using the <span class="inline_code"><a href="#rop">
bvbltparams.op.rop</a></span> code of <span class="inline_code">0xAAAA</span> (copy destination to destination), and 
with the <span class="inline_code">BVFLAG_ASYNC</span> flag <span class="underline">not</span> set.&nbsp; Alternatively, the NOP BLT may set the
<span class="inline_code">BVFLAG_ASYNC</span> and provide a <span class="inline_code"><a href="#callbackfn">
bvbltparams.callbackfn</a></span>.&nbsp; <em>To facilitate implementations, a valid destination surface should be 
specified.</em></p>
<p class="imponly"><strong>Implementations Only<br />
<br />
</strong>In general, this BLTsville specification has avoided placing any requirement on implementations for specific 
operations.&nbsp; However, in support of this special case, support for these NOP BLTs will need to be an implementation
<span class="underline"><strong>requirement</strong></span>. </p>
<p class="Code_Header_3">bvbltparams.flags - BVFLAG_BATCH_BEGIN/CONTINUE/END</p>
<p>These flags are used to control batching of BLTs for two main reasons:</p>
<ol>
	<li>To group small, similar BLTs to consolidate overhead.&nbsp; For example, the BLTs associated with rendering each 
	character in a word.</li>
	<li>To group related BLTs, which may allow an implementation to perform a more efficient, but equivalent set of operations.</li>
</ol>
<p>See <a href="#batching">Batching</a> for details.</p>
<p class="Code_Header_3">bvbltparams.flags - <a name="BVFLAG_SRC2_AUXDSTRECT">BVFLAG_SRC2</a>/<a name="BVFLAG_MASK_AUXDSTRECT">MASK_AUXDSTRECT</a></p>
<p>These flags are used to indicate that the bvbltparams.src2auxdstrect and bvbltparams.maskauxdstrect are to be used.&nbsp; 
See these entries below for details. These flags are likely to be ignored except for the special case explained below, 
so they should be used only when necessary.</p>
<p class="Code_Header_2"><a name="rop">bvbltparams.op.rop</a></p>
<p class="code_block">unsigned short op; /* input */ </p>
<p>When <span class="inline_code"><a href="#BVFLAG_ROP">BVFLAG_ROP</a></span> is set in the <span class="inline_code">
<a href="#flags">bvbltparams.flags</a></span> member, the <span class="inline_code"><a href="#op">bvbltparams.op</a></span> 
union is treated as <span class="inline_code">rop</span>.&nbsp; Raster OPerations are binary operations performed on the 
bits of the inputs:</p>
<ul>
	<li>ROP1s have one source:&nbsp; the destination.&nbsp; Two bits are sufficient to specify the four possible (2<sup>2</sup>) 
	ROP1 operations.</li>
	<li>ROP2s have two sources:&nbsp; the destination and a source.&nbsp; Four bits are used to specify the sixteen (2<sup>2+2</sup>) 
	ROP2 operations.</li>
	<li>ROP3s have three sources:&nbsp; the destination, a source (source 1), and a pattern (a.k.a. brush), which we call 
	source 2 in BLTsville.&nbsp; Eight bits are used to specify the 256 (2<sup>2+2+2</sup>) ROP3 operations.</li>
	<li>ROP4s have four sources:&nbsp; the destination, two sources, and a mask.&nbsp; Sixteen bits are used to specify 
	the 65,536 (2<sup>2+2+2+2</sup>) ROP4 operations.</li>
</ul>
<p>BLTsville&#39;s <span class="inline_code">rop</span> element is used to specify a ROP4, but anything from ROP1 up to ROP4 
can be defined using this member:</p>
<ul>
	<li>To specify an 8-bit ROP3 as a 16-bit ROP4, replicate the 8 bits twice:&nbsp; 0x2323.</li>
	<li>To specify a 4-bit ROP2 as a 16-bit ROP4, replicate the 4 bits four times:&nbsp; 0x2222.</li>
	<li>To specify a 2-bit ROP1 as a 16-bit ROP4, replicate the 2 bits eight times:&nbsp; 0x5555.</li>
</ul>
<p class="note">NOTE:&nbsp;
By far the most common ROP used will be 0xCCCC, which indicates a simple copy from source 1 to the destination.</p>
<p>The table below is the magic decoder ring: </p>
<table class="indent">
	<tr>
		<td>Mask</td>
		<td class="ctr">&nbsp;1&nbsp;</td>
		<td class="ctr">&nbsp;1&nbsp;</td>
		<td class="ctr">&nbsp;1&nbsp;</td>
		<td class="ctr">&nbsp;1&nbsp;</td>
		<td class="ctr">&nbsp;1&nbsp;</td>
		<td class="ctr">&nbsp;1&nbsp;</td>
		<td class="ctr">&nbsp;1&nbsp;</td>
		<td class="ctr">&nbsp;1&nbsp;</td>
		<td class="ctr">&nbsp;0&nbsp;</td>
		<td class="ctr">&nbsp;0&nbsp;</td>
		<td class="ctr">&nbsp;0&nbsp;</td>
		<td class="ctr">&nbsp;0&nbsp;</td>
		<td class="ctr">&nbsp;0&nbsp;</td>
		<td class="ctr">&nbsp;0&nbsp;</td>
		<td class="ctr">&nbsp;0&nbsp;</td>
		<td class="ctr">&nbsp;0&nbsp;</td>
	</tr>
	<tr>
		<td class="red_left">Source 2 </td>
		<td class="red_center">&nbsp;1&nbsp;</td>
		<td class="red_center">&nbsp;1&nbsp;</td>
		<td class="red_center">&nbsp;1&nbsp;</td>
		<td class="red_center">&nbsp;1&nbsp;</td>
		<td class="red_center">&nbsp;0&nbsp;</td>
		<td class="red_center">&nbsp;0&nbsp;</td>
		<td class="red_center">&nbsp;0&nbsp;</td>
		<td class="red_center">&nbsp;0&nbsp;</td>
		<td class="red_center">&nbsp;1&nbsp;</td>
		<td class="red_center">&nbsp;1&nbsp;</td>
		<td class="red_center">&nbsp;1&nbsp;</td>
		<td class="red_center">&nbsp;1&nbsp;</td>
		<td class="red_center">&nbsp;0&nbsp;</td>
		<td class="red_center">&nbsp;0&nbsp;</td>
		<td class="red_center">&nbsp;0&nbsp;</td>
		<td class="red_center">&nbsp;0&nbsp;</td>
	</tr>
	<tr>
		<td class="grn_left">Source 1 </td>
		<td class="grn_center">&nbsp;1&nbsp;</td>
		<td class="grn_center">&nbsp;1&nbsp;</td>
		<td class="grn_center">&nbsp;0&nbsp;</td>
		<td class="grn_center">&nbsp;0&nbsp;</td>
		<td class="grn_center">&nbsp;1&nbsp;</td>
		<td class="grn_center">&nbsp;1&nbsp;</td>
		<td class="grn_center">&nbsp;0&nbsp;</td>
		<td class="grn_center">&nbsp;0&nbsp;</td>
		<td class="grn_center">&nbsp;1&nbsp;</td>
		<td class="grn_center">&nbsp;1&nbsp;</td>
		<td class="grn_center">&nbsp;0&nbsp;</td>
		<td class="grn_center">&nbsp;0&nbsp;</td>
		<td class="grn_center">&nbsp;1&nbsp;</td>
		<td class="grn_center">&nbsp;1&nbsp;</td>
		<td class="grn_center">&nbsp;0&nbsp;</td>
		<td class="grn_center">&nbsp;0&nbsp;</td>
	</tr>
	<tr>
		<td class="blue_left_botbord">Destination </td>
		<td class="blue_center_botbord">&nbsp;1&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;0&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;1&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;0&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;1&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;0&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;1&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;0&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;1&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;0&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;1&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;0&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;1&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;0&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;1&nbsp;</td>
		<td class="blue_center_botbord">&nbsp;0&nbsp;</td>
	</tr>
	<tr>
		<td class="left_topbord">Raster Operation </td>
		<td class="center_topbord">&nbsp;15&nbsp;</td>
		<td class="center_topbord">&nbsp;14&nbsp;</td>
		<td class="center_topbord">&nbsp;13&nbsp;</td>
		<td class="center_topbord">&nbsp;12&nbsp;</td>
		<td class="center_topbord">&nbsp;11&nbsp;</td>
		<td class="center_topbord">&nbsp;10&nbsp;</td>
		<td class="center_topbord">&nbsp;&nbsp;9&nbsp;</td>
		<td class="center_topbord">&nbsp;&nbsp;8&nbsp;</td>
		<td class="center_topbord">&nbsp;&nbsp;7&nbsp;</td>
		<td class="center_topbord">&nbsp;&nbsp;6&nbsp;</td>
		<td class="center_topbord">&nbsp;&nbsp;5&nbsp;</td>
		<td class="center_topbord">&nbsp;&nbsp;4&nbsp;</td>
		<td class="center_topbord">&nbsp;&nbsp;3&nbsp;</td>
		<td class="center_topbord">&nbsp;&nbsp;2&nbsp;</td>
		<td class="center_topbord">&nbsp;&nbsp;1&nbsp;</td>
		<td class="center_topbord">&nbsp;&nbsp;0&nbsp;</td>
	</tr>
</table>
<br />
For example, to specify an operation that uses the mask to choose between source 1 and destination (source 1 when mask is 
1, destination when mask is 0), a client would calculate the bottom line by parsing each column:<br />
<br />
When mask is 1 (the first eight columns), the <span class="inline_code">rop</span> matches the source 1 row.&nbsp; When 
mask is 0 (the last eight columns), the <span class="inline_code">rop</span> matches the destination row.<br />
<br />
<table class="indent">
	<tr>
		<td class="left_topbord">Raster Operation </td>
		<td class="red_center_topbord">&nbsp;1&nbsp;</td>
		<td class="red_center_topbord">&nbsp;1&nbsp;</td>
		<td class="red_center_topbord">&nbsp;1&nbsp;</td>
		<td class="red_center_topbord">&nbsp;1&nbsp;</td>
		<td class="red_center_topbord">&nbsp;0&nbsp;</td>
		<td class="red_center_topbord">&nbsp;0&nbsp;</td>
		<td class="red_center_topbord">&nbsp;0&nbsp;</td>
		<td class="red_center_topbord">&nbsp;0&nbsp;</td>
		<td class="blu_center_topbord">&nbsp;1&nbsp;</td>
		<td class="blu_center_topbord">&nbsp;0&nbsp;</td>
		<td class="blu_center_topbord">&nbsp;1&nbsp;</td>
		<td class="blu_center_topbord">&nbsp;0&nbsp;</td>
		<td class="blu_center_topbord">&nbsp;1&nbsp;</td>
		<td class="blu_center_topbord">&nbsp;0&nbsp;</td>
		<td class="blu_center_topbord">&nbsp;1&nbsp;</td>
		<td class="blu_center_topbord">&nbsp;0&nbsp;</td>
	</tr>
</table>
<br />
So the <span class="inline_code">rop</span> for this operation would be 0xF0AA.<br />
<br />
Here is a list of some commonly used raster operations that have been given names:<br />
<br />
<table class="indent_thick_bord">
	<tr>
		<td class="thin_bord_dbl_botbord"><strong>ROP </strong></td>
		<td class="thin_bord_dbl_botbord"><strong>Constant</strong></td>
		<td class="thin_bord_dbl_botbord"><strong>Description</strong></td>
	</tr>
	<tr>
		<td class="thin_bord">BLACKNESS</td>
		<td class="thin_bord">0x0000</td>
		<td class="thin_bord">Set all destination bits to black (0).&nbsp; Dest = 0</td>
	</tr>
	<tr>
		<td class="thin_bord">NOTSRCERASE</td>
		<td class="thin_bord">0x1111</td>
		<td class="thin_bord">Dest = ~Src1 &amp; ~Dest = ~(Src1 | Dest)</td>
	</tr>
	<tr>
		<td class="thin_bord">NOTSRCCOPY</td>
		<td class="thin_bord">0x3333</td>
		<td class="thin_bord">Dest = ~Src1</td>
	</tr>
	<tr>
		<td class="thin_bord">SRCERASE</td>
		<td class="thin_bord">0x4444</td>
		<td class="thin_bord">Dest = Src1 &amp; ~Dest</td>
	</tr>
	<tr>
		<td class="thin_bord">DSTINVERT</td>
		<td class="thin_bord">0x5555</td>
		<td class="thin_bord">Invert (NOT) the destination bits.&nbsp; Dest = ~Dest</td>
	</tr>
	<tr>
		<td class="thin_bord">PATINVERT</td>
		<td class="thin_bord">0x5A5A</td>
		<td class="thin_bord">XOR with Src2.&nbsp; Dest = Src2 ^ Dest</td>
	</tr>
	<tr>
		<td class="thin_bord">SRCINVERT</td>
		<td class="thin_bord">0x6666</td>
		<td class="thin_bord">XOR with Src1.&nbsp; Dest = Src1 ^ Dest</td>
	</tr>
	<tr>
		<td class="thin_bord">SRCAND</td>
		<td class="thin_bord">0x8888</td>
		<td class="thin_bord">Dest = Src1 &amp; Dest</td>
	</tr>
	<tr>
		<td class="thin_bord">NOP</td>
		<td class="thin_bord">0xAAAA</td>
		<td class="thin_bord">Dest = Dest</td>
	</tr>
	<tr>
		<td class="thin_bord">MERGEPAINT</td>
		<td class="thin_bord">0xBBBB</td>
		<td class="thin_bord">Dest = ~Src1 | Dest</td>
	</tr>
	<tr>
		<td class="thin_bord">MERGECOPY</td>
		<td class="thin_bord">0xC0C0</td>
		<td class="thin_bord">Dest = Src1 &amp; Src2</td>
	</tr>
	<tr>
		<td class="thin_bord">SRCCOPY</td>
		<td class="thin_bord">0xCCCC</td>
		<td class="thin_bord">Dest = Src1</td>
	</tr>
	<tr>
		<td class="thin_bord">SRCPAINT</td>
		<td class="thin_bord">0xEEEE</td>
		<td class="thin_bord">OR with Src1.&nbsp; Dest = Src1 | Dest</td>
	</tr>
	<tr>
		<td class="thin_bord">PATCOPY</td>
		<td class="thin_bord">0xF0F0</td>
		<td class="thin_bord">Copy source 2 to destination.&nbsp; Dest = Src2</td>
	</tr>
	<tr>
		<td class="thin_bord">PATPAINT</td>
		<td class="thin_bord">0xFBFB</td>
		<td class="thin_bord">Dest =&nbsp; ~Src1 | Src2 | Dest</td>
	</tr>
	<tr>
		<td class="thin_bord">WHITENESS</td>
		<td class="thin_bord">0xFFFF</td>
		<td class="thin_bord">Set all destination bits to white (1).&nbsp; Dest = 1</td>
	</tr>
</table>
<br />
<span class="Code_Header_2"><a name="blend">bvbltparams.op.blend</a></span>
<p class="code_block">enum bvblend blend; /* input */</p>
<p>When <span class="inline_code"><a href="#BVFLAG_BLEND">BVFLAG_BLEND</a></span> is set in the
<span class="inline_code"><a href="#flags">bvbltparams.flags</a></span> member, the <span class="inline_code">
<a href="#op">bvbltparams.op</a></span> union is treated as a <span class="inline_code">blend</span>.</p>
<p>To specify the blend, the client fills in <span class="inline_code">blend</span> with one of the
<span class="inline_code"><a href="#bvblend">bvblend</a></span> values.</p>
<p><span class="inline_code"><a href="#bvblend">bvblend</a></span> is an enumeration assembled from sets of fields.&nbsp; 
The values specified may be extended beyond those that are explicitly defined using the definitions in the
<span class="filename">bvblend.h</span> header file.</p>
<p>The first 4 bits are the format.&nbsp; Currently two format groups are defined, but others can be added.&nbsp; The remainder 
of the bits are used as defined by the individual format:</p>
<table class="indent">
	<tr>
		<td valign="top">1.</td>
		<td><span class="Code_Header_3">BVBLENDDEF_FORMAT_CLASSIC</span><br />
		<br />
		The <span class="inline_code">BVBLENDDEF_FORMAT_CLASSIC</span> is meant to handle the classic Porter-Duff equations. 
		It can also handle the DirectFB blending.<br />
		<br />
		<span class="inline_code">BVBLENDDEF_FORMAT_CLASSIC</span> is based on the following equations:<br />
		<div>
			<p class="indent">C<sub>d</sub> = K<sub>1</sub>C<sub>1</sub> + K<sub>2</sub>C<sub>2</sub><br />
			A<sub>d</sub> = K<sub>3</sub>A<sub>1</sub> + K<sub>4</sub>A<sub>2</sub></p>
		</div>
		where:<br />
		<div>
			<p class="indent">C<sub>d</sub>: destination color<br />
			C<sub>1</sub>: source 1 color<br />
			C<sub>2</sub>: source 2 color<br />
			A<sub>d</sub>: destination alpha<br />
			A<sub>1</sub>: source 1 alpha<br />
			A<sub>2</sub>: source 2 alpha<br />
			K<sub>#</sub>: one of the constants defined using the bitfields below</p>
		</div>
		The 28 bits for <span class="inline_code">BVBLENDDEF_FORMAT_CLASSIC</span> are divided into 5 sections.<br />
		<br />
		The most significant 4 bits are modifiers, used to include additional alpha values from global or remote sources.<br />
		<br />
		[27] The most significant bit indicates that a remote alpha is to be included in the blend. The format of this is 
		defined by <span class="inline_code"><a href="#maskgeom">bvbltparams.maskgeom.format</a></span>.<br />
		<br />
		[26] The next bit is reserved.<br />
		<br />
		[25:24] The next 2 bits are used to indicate that a global alpha is to be included, and what its format is:<br />
		<div>
			<p class="indent">00: no global included<br />
			01: global included; bvbltparams.globalalpha.size8 is used (0 -&gt; 255)<br />
			10: this value is reserved<br />
			11: global included; bvbltparams.flogalalpha.fp is used (0.0 -&gt; 1.0) </p>
		</div>
		The remaining bits are divided into 4 sections, one to define each of the constants:<br />
		<br />
		[23:18] - K1<br />
		[17:12] - K2<br />
		[11:6] - K3<br />
		[5:0] - K4<br />
		<br />
		The format is the same for all 4 constant fields:<br />
		<br />
		[5:4] The first 2 bits of each field indicates the way in which the other 2 fields are interpreted:<br />
		<div>
			<p class="indent">00: only As: the other two fields contain only As; there should be only one valid A value 
			between the two fields<br />
			01: minimum: the value of the constant is the minimum of the two fields<br />
			10: maximum: the value of the constant is the maximum of the two fields<br />
			11: only Cs: the other two fields contain only Cs; there should be only one valid C value between the two fields</p>
		</div>
		[3:2] The middle 2 bits of each field contain the inverse field:<br />
		<div>
			<p class="indent">00: 1-C1 (&quot;don&#39;t care&quot; for &quot;only As&quot;)<br />
			01: 1-A1 (&quot;don&#39;t care&quot; for &quot;only Cs&quot;)<br />
			10: 1-C2 (&quot;don&#39;t care&quot; for &quot;only As&quot;)<br />
			11: 1-A2 (&quot;don&#39;t care&quot; for &quot;only Cs&quot;)</p>
		</div>
		[1:0] The last 2 bits if each field contain the normal field:<br />
		<div>
			<p class="indent">00: C1 (&quot;don&#39;t care&quot; for &quot;only As&quot;)<br />
			01: A1 (&quot;don&#39;t care&quot; for &quot;only Cs&quot;)<br />
			10: C2 (&quot;don&#39;t care&quot; for &quot;only As&quot;)<br />
			11: A2 (&quot;don&#39;t care&quot; for &quot;only Cs&quot;)</p>
		</div>
		EXCEPTIONS:<br />
		<br />
		00 00 00 - The value 00 00 00, which normally would indicate &quot;only As&quot; with two &quot;don&#39;t care&quot; fields, is interpreted 
		as a constant of 0.<br />
		<br />
		11 11 11 - The value 11 11 11, which normally would indicate &quot;only Cs&quot; with two &quot;don&#39;t care&quot; fields, is interpreted 
		as a constant of 1.<br />
		<br />
		<span class="Header4">Constants</span><br />
		<br />
		Put together, these can define portions of the blend equations that can be put together in a variety of ways:<br />
		<br />
		<table class="indent_thick_bord">
			<tr>
				<td class="rt_thick_bord">
				<table>
					<tr>
						<td class="thin_bord">00 00 00</td>
						<td class="thin_bord">undefined -&gt; zero</td>
					</tr>
					<tr>
						<td class="thin_bord">00 00 01</td>
						<td class="thin_bord">A1 (preferred)</td>
					</tr>
					<tr>
						<td class="thin_bord">00 00 10</td>
						<td class="thin_bord">undefined</td>
					</tr>
					<tr>
						<td class="thin_bord">00 00 11</td>
						<td class="thin_bord">A2 (preferred)</td>
					</tr>
					<tr>
						<td class="thin_bord">00 01 00</td>
						<td class="thin_bord">1-A1 (preferred)</td>
					</tr>
					<tr>
						<td class="thin_bord">00 01 01</td>
						<td class="thin_bord">undefined</td>
					</tr>
					<tr>
						<td class="thin_bord">00 01 10</td>
						<td class="thin_bord">1-A1 (use 00 01 00)</td>
					</tr>
					<tr>
						<td class="thin_bord">00 01 11</td>
						<td class="thin_bord">undefined</td>
					</tr>
					<tr>
						<td class="thin_bord">00 10 00</td>
						<td class="thin_bord">undefined</td>
					</tr>
					<tr>
						<td class="thin_bord">00 10 01</td>
						<td class="thin_bord">A1 (use 00 00 01)</td>
					</tr>
					<tr>
						<td class="thin_bord">00 10 10</td>
						<td class="thin_bord">undefined</td>
					</tr>
					<tr>
						<td class="thin_bord">00 10 11</td>
						<td class="thin_bord">A2 (use 00 00 11)</td>
					</tr>
					<tr>
						<td class="thin_bord">00 11 00</td>
						<td class="thin_bord">1-A2 (preferred)</td>
					</tr>
					<tr>
						<td class="thin_bord">00 11 01</td>
						<td class="thin_bord">undefined</td>
					</tr>
					<tr>
						<td class="thin_bord">00 11 10</td>
						<td class="thin_bord">1-A2 (use 00 11 00)</td>
					</tr>
					<tr>
						<td class="thin_bord">00 11 11</td>
						<td class="thin_bord">undefined</td>
					</tr>
				</table>
				</td>
				<td class="rt_thick_bord">
				<table>
					<tr>
						<td class="thin_bord">01 00 00</td>
						<td class="thin_bord">min(C1,1-C1)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 00 01</td>
						<td class="thin_bord">min(A1,1-C1)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 00 10</td>
						<td class="thin_bord">min(C2,1-C1)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 00 11</td>
						<td class="thin_bord">min(A2,1-C1)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 01 00</td>
						<td class="thin_bord">min(C1,1-A1)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 01 01</td>
						<td class="thin_bord">min(A1,1-A1)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 01 10</td>
						<td class="thin_bord">min(C2,1-A1)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 01 11</td>
						<td class="thin_bord">min(A2,1-A1)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 10 00</td>
						<td class="thin_bord">min(C1,1-C2)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 10 01</td>
						<td class="thin_bord">min(A1,1-C2)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 10 10</td>
						<td class="thin_bord">min(C2,1-C2)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 10 11</td>
						<td class="thin_bord">min(A2,1-C2)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 11 00</td>
						<td class="thin_bord">min(C1,1-A2)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 11 01</td>
						<td class="thin_bord">min(A1,1-A2)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 11 10</td>
						<td class="thin_bord">min(C2,1-A2)</td>
					</tr>
					<tr>
						<td class="thin_bord">01 11 11</td>
						<td class="thin_bord">min(A2,1-A2)</td>
					</tr>
				</table>
				</td>
				<td class="rt_thick_bord">
				<table>
					<tr>
						<td class="thin_bord">10 00 00</td>
						<td class="thin_bord">max(C1,1-C1)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 00 01</td>
						<td class="thin_bord">max(A1,1-C1)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 00 10</td>
						<td class="thin_bord">max(C2,1-C1)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 00 11</td>
						<td class="thin_bord">max(A2,1-C1)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 01 00</td>
						<td class="thin_bord">max(C1,1-A1)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 01 01</td>
						<td class="thin_bord">max(A1,1-A1)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 01 10</td>
						<td class="thin_bord">max(C2,1-A1)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 01 11</td>
						<td class="thin_bord">max(A2,1-A1)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 10 00</td>
						<td class="thin_bord">max(C1,1-C2)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 10 01</td>
						<td class="thin_bord">max(A1,1-C2)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 10 10</td>
						<td class="thin_bord">max(C2,1-C2)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 10 11</td>
						<td class="thin_bord">max(A2,1-C2)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 11 00</td>
						<td class="thin_bord">max(C1,1-A2)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 11 01</td>
						<td class="thin_bord">max(A1,1-A2)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 11 10</td>
						<td class="thin_bord">max(C2,1-A2)</td>
					</tr>
					<tr>
						<td class="thin_bord">10 11 11</td>
						<td class="thin_bord">max(A2,1-A2)</td>
					</tr>
				</table>
				</td>
				<td>
				<table>
					<tr>
						<td class="thin_bord">11 00 00</td>
						<td class="thin_bord">undefined</td>
					</tr>
					<tr>
						<td class="thin_bord">11 00 01</td>
						<td class="thin_bord">1-C1 (use 11 00 11)</td>
					</tr>
					<tr>
						<td class="thin_bord">11 00 10</td>
						<td class="thin_bord">undefined</td>
					</tr>
					<tr>
						<td class="thin_bord">11 00 11</td>
						<td class="thin_bord">1-C1 (preferred)</td>
					</tr>
					<tr>
						<td class="thin_bord">11 01 00</td>
						<td class="thin_bord">C1 (use 11 11 00)</td>
					</tr>
					<tr>
						<td class="thin_bord">11 01 01</td>
						<td class="thin_bord">undefined</td>
					</tr>
					<tr>
						<td class="thin_bord">11 01 10</td>
						<td class="thin_bord">C2 (use 11 11 10)</td>
					</tr>
					<tr>
						<td class="thin_bord">11 01 11</td>
						<td class="thin_bord">undefined</td>
					</tr>
					<tr>
						<td class="thin_bord">11 10 00</td>
						<td class="thin_bord">undefined</td>
					</tr>
					<tr>
						<td class="thin_bord">11 10 01</td>
						<td class="thin_bord">1-C2 (use 11 10 11)</td>
					</tr>
					<tr>
						<td class="thin_bord">11 10 10</td>
						<td class="thin_bord">undefined</td>
					</tr>
					<tr>
						<td class="thin_bord">11 10 11</td>
						<td class="thin_bord">1-C2 (preferred)</td>
					</tr>
					<tr>
						<td class="thin_bord">11 11 00</td>
						<td class="thin_bord">C1 (preferred)</td>
					</tr>
					<tr>
						<td class="thin_bord">11 11 01</td>
						<td class="thin_bord">undefined</td>
					</tr>
					<tr>
						<td class="thin_bord">11 11 10</td>
						<td class="thin_bord">C2 (preferred)</td>
					</tr>
					<tr>
						<td class="thin_bord">11 11 11</td>
						<td class="thin_bord">undefined -&gt; one</td>
					</tr>
				</table>
				</td>
			</tr>
		</table>
		<span class="Header4"><br />
		DirectFB Example</span><br />
		<br />
		Putting these together into the proper constants, the blending equations can be built for different APIs.&nbsp; 
		Here is how DirectFB would be mapped:<br />
		<br />
		For DirectFB, the
		<a href="http://directfb.org/docs/DirectFB_Reference_1_2/IDirectFBSurface_SetSrcBlendFunction.html" class="inline_code">
		SetSrcBlendFunction()</a> and
		<a href="http://directfb.org/docs/DirectFB_Reference_1_2/IDirectFBSurface_SetDstBlendFunction.html" class="inline_code">
		SetDstBlendFunction()</a> can specify 121 combinations of blends (11 x 11). It&#39;s impractical to specify these combinations 
		individually. Instead, the settings indicated by each call should be bitwise OR&#39;d to make the proper single value 
		used in BLTsville.<br />
		<br />
		<table class="code_block">
			<tr>
				<td class="ctr">&nbsp;</td>
				<td colspan="5" class="ctr"><strong>32-bit Binary Value</strong></td>
			</tr>
			<tr>
				<td><strong>
				<a href="http://directfb.org/docs/DirectFB_Reference_1_2/IDirectFBSurface_SetSrcBlendFunction.html">SetSrcBlendFunction()</a></strong></td>
				<td class="ctr"><strong>[VendorID]</strong></td>
				<td class="ctr"><strong>&nbsp;[--K1--] </strong></td>
				<td class="ctr"><strong>&nbsp;[--K2--] </strong></td>
				<td class="ctr"><strong>&nbsp;[--K3--] </strong></td>
				<td class="ctr"><strong>&nbsp;[--K4--] </strong></td>
			</tr>
			<tr>
				<td>DSBF_ZERO</td>
				<td class="ctr">0000 0000</td>
				<td class="ctr">00 00 00</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">00 00 00</td>
				<td class="ctr">xx xx xx</td>
			</tr>
			<tr>
				<td>DSBF_ONE</td>
				<td class="ctr">0000 0000</td>
				<td class="ctr">11 11 11</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">11 11 11</td>
				<td class="ctr">xx xx xx</td>
			</tr>
			<tr>
				<td>DSBF_SRCCOLOR</td>
				<td class="ctr">0000 0000</td>
				<td class="ctr">11 11 00</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">00 00 01</td>
				<td class="ctr">xx xx xx</td>
			</tr>
			<tr>
				<td>DSBF_INVSRCCOLOR</td>
				<td class="ctr">0000 0000</td>
				<td class="ctr">11 00 11</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">00 01 00</td>
				<td class="ctr">xx xx xx</td>
			</tr>
			<tr>
				<td>DSBF_SRCALPHA</td>
				<td class="ctr">0000 0000</td>
				<td class="ctr">00 00 01</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">00 00 01</td>
				<td class="ctr">xx xx xx</td>
			</tr>
			<tr>
				<td>DSBF_INVSRCALPHA</td>
				<td class="ctr">0000 0000</td>
				<td class="ctr">00 01 00</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">00 01 00</td>
				<td class="ctr">xx xx xx</td>
			</tr>
			<tr>
				<td>DSBF_DESTCOLOR</td>
				<td class="ctr">0000 0000</td>
				<td class="ctr">11 11 10</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">00 00 11</td>
				<td class="ctr">xx xx xx</td>
			</tr>
			<tr>
				<td>DSBF_INVDESTCOLOR</td>
				<td class="ctr">0000 0000</td>
				<td class="ctr">11 10 11</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">00 11 00</td>
				<td class="ctr">xx xx xx</td>
			</tr>
			<tr>
				<td>DSBF_DESTALPHA</td>
				<td class="ctr">0000 0000</td>
				<td class="ctr">00 00 11</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">00 00 11</td>
				<td class="ctr">xx xx xx</td>
			</tr>
			<tr>
				<td>DSBF_INVDESTALPHA</td>
				<td class="ctr">0000 0000</td>
				<td class="ctr">00 11 00</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">00 11 00</td>
				<td class="ctr">xx xx xx</td>
			</tr>
			<tr>
				<td>DSBF_SRCALPHASAT</td>
				<td class="ctr">0000 0000</td>
				<td class="ctr">01 11 01</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">11 11 11</td>
				<td class="ctr">xx xx xx</td>
			</tr>
		</table>
		<br />
		<table class="code_block">
			<tr>
				<td class="ctr">&nbsp;</td>
				<td colspan="5" class="ctr"><strong>32-bit Binary Value</strong></td>
			</tr>
			<tr>
				<td><strong>
				<a href="http://directfb.org/docs/DirectFB_Reference_1_2/IDirectFBSurface_SetDstBlendFunction.html">SetDstBlendFunction()</a></strong></td>
				<td class="ctr"><strong>[VendorID]</strong></td>
				<td class="ctr"><strong>&nbsp;[--K1--] </strong></td>
				<td class="ctr"><strong>&nbsp;[--K2--] </strong></td>
				<td class="ctr"><strong>&nbsp;[--K3--] </strong></td>
				<td class="ctr"><strong>&nbsp;[--K4--] </strong></td>
			</tr>
			<tr>
				<td>DSBF_ZERO</td>
				<td class="ctr">0000 0000</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">00 00 00</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">00 00 00</td>
			</tr>
			<tr>
				<td>DSBF_ONE</td>
				<td class="ctr">0000 0000</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">11 11 11</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">11 11 11</td>
			</tr>
			<tr>
				<td>DSBF_SRCCOLOR</td>
				<td class="ctr">0000 0000</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">11 11 00</td>
				<td class="ctr">xx xx xx</td>
				<td class="ctr">00 00 01</td>
			</tr>
			<tr>
				<td>etc.</td>
				<td class="ctr">&nbsp;</td>
				<td class="ctr">&nbsp;</td>
				<td class="ctr">&nbsp;</td>
				<td class="ctr">&nbsp;</td>
				<td>&nbsp;</td>
			</tr>
		</table>
		<br />
		<span class="Header4">Porter-Duff</span><br />
		<br />
		For Porter-Duff blends, the equations can be more specifically defined. For convenience, these are enumerated in 
		the <span class="inline_code">bvblend.h</span> header. These enumerations utilize only the local alpha in the equations 
		as indicated. To use global or remote alpha, these enumerations need to be modified. For example, to include the 
		global alpha in the Porter-Duff <span class="inline_code">BVBLEND_SRC1OVER</span> blend, the blend could be defined 
		like this:<br />
		<br />
		<div>
			<table class="indent">
				<tr>
					<td valign="top"><span class="inline_code">params.op.blend =</span></td>
					<td><span class="inline_code">BVBLEND_SRC1OVER +<br />
					BVBLENDDEF_GLOBAL_UCHAR;</span></td>
				</tr>
			</table>
		</div>
		<br />
		To include the remote alpha, the blend could be defined like this:<br />
		<br />
		<div>
			<table class="indent">
				<tr>
					<td valign="top"><span class="inline_code">params.op.blend =</span></td>
					<td><span class="inline_code">BVBLEND_SRC1OVER +<br />
					BVBLENDDEF_REMOTE;</span></td>
				</tr>
			</table>
		</div>
		<br />
		And to include both:<br />
		<br />
		<div>
			<table class="indent">
				<tr>
					<td valign="top"><span class="inline_code">params.op.blend =</span></td>
					<td><span class="inline_code">BVBLEND_SRC1OVER +<br />
					BVBLENDDEF_GLOBAL_UCHAR +<br />
					BVBLENDDEF_REMOTE;</span></td>
				</tr>
			</table>
		</div>
		<br />
		Note that if the source color formats include local alphas, the local alphas, global alpha, and remote alpha will 
		be used together.<br />
		<br />
		Note also that the equations assume the surfaces are premultiplied. So if the surface formats indicate that they 
		are not premultiplied, the alpha multiplication of each color is done prior to using the surface values in the equations.<br />
		<br />
		For example, <span class="inline_code">BVBLEND_SRC1OVER</span> specifies the equations:<br />
		<table class="indent">
			<tr>
				<td>C<sub>d</sub> = C<sub>1</sub> + (1 - A<sub>1</sub>)C<sub>2</sub><br />
				A<sub>d</sub> = A<sub>1</sub> + (1 - A<sub>1</sub>)A<sub>2</sub> </td>
			</tr>
		</table>
		<br />
		If the format of surface 1 is non-premultiplied, the equations are modified to include the multiplication explicitly:<br />
		<br />
		<table class="indent">
			<tr>
				<td>C<sub>d</sub> = A<sub>1</sub>C<sub>1</sub> + (1 - A<sub>1</sub>)C<sub>2</sub><br />
				A<sub>d</sub> = A<sub>1</sub> + (1 - A<sub>1</sub>)A<sub>2</sub> </td>
			</tr>
		</table>
		<br />
		Likewise, if the format of surface 2 is non-premultiplied, the equations are modified for this:<br />
		<br />
		<table class="indent">
			<tr>
				<td>
				<div>
					C<sub>d</sub> = C<sub>1</sub> + (1 - A<sub>1</sub>)A<sub>2</sub>C<sub>2</sub><br />
					A<sub>d</sub> = A<sub>1</sub> + (1 - A<sub>1</sub>)A<sub>2</sub> </div>
				</td>
			</tr>
		</table>
		<br />
		When including global or remote alphas, these values are used to modify the source 1 value values before being used 
		in the blend equation:<br />
		<br />
		<table class="indent">
			<tr>
				<td class="ctr">C<sub>1</sub> = A<sub>g</sub>C<sub>1</sub><br />
				A<sub>1</sub> = A<sub>g</sub>A<sub>1</sub></td>
				<td style="width: 20%" class="ctr">-or-</td>
				<td class="ctr">C<sub>1</sub> = A<sub>r</sub>C<sub>1</sub><br />
				A<sub>1</sub> = A<sub>r</sub>A<sub>1</sub></td>
				<td class="ctr">-or-</td>
				<td class="ctr">C<sub>1</sub> = A<sub>r</sub>A<sub>g</sub>C<sub>1</sub><br />
				A<sub>1</sub> = A<sub>r</sub>A<sub>g</sub>A<sub>1</sub></td>
			</tr>
		</table>
		<br />
		</td>
	</tr>
	<tr>
		<td valign="top">2.</td>
		<td><span class="Code_Header_3"><strong><a name="BVBLENDDEF_FORMAT_ESSENTIAL0">BVBLENDDEF_FORMAT_ESSENTIAL</a></strong></span><br />
		<br />
		The essential blending equations are based on the blending equations in common image manipulation programs.<pre class="indent"><code>BVBLEND_LIGHTEN      max(src1, src2)
BVBLEND_DARKEN       min(src1, src2)
BVBLEND_MULTIPLY     (src1 * src2) / 255
BVBLEND_AVERAGE      (src1 + src2) / 2
BVBLEND_ADD          src1 + src2 (saturated)
BVBLEND_SUBTRACT     src1 + src2 - 255 (saturated)
BVBLEND_DIFFERENCE   abs(src - src2)
BVBLEND_NEGATION     255 - abs(255 - src1 - src2)
BVBLEND_SCREEN       255 - (((255 - src1) * (255 - src2)) / 256)
BVBLEND_EXCLUSION    src1 + src2 - ((2 * src1 * src2) / 255)
BVBLEND_OVERLAY      (src2 &lt; 128) ? (2 * src1 * src2 / 255) : (255 - 2 * (255 - src1) * (255 - src2) / 255)
BVBLEND_SOFT_LIGHT   (src2 &lt; 128) ? (2 * ((src1 &gt;&gt; 1) + 64)) * ((float)src2 / 255) : (255 - (2 * (255 - ((src1 &gt;&gt; 1) + 64)) * (float)(255 - src2) / 255))
BVBLEND_HARD_LIGHT   (src1 &lt; 128) ? (2 * src2 * src1 / 255) : (255 - 2 * (255 - src2) * (255 - src1) / 255)
BVBLEND_COLOR_DODGE  (src2 == 255) ? src2 : min(255, ((src1 &lt;&lt; 8) / (255 - src2))
BVBLEND_COLOR_BURN   (src2 == 0) ? src2 : max(0, (255 - ((255 - src1) &lt;&lt; 8 ) / src2))))
BVBLEND_LINEAR_DODGE same as BVBLEND_ADD
BVBLEND_LINEAR_BURN  same as BVBLEND_SUBTRACT
BVBLEND_LINEAR_LIGHT (src2 &lt; 128) ? LINEAR_BURN(src1,(2 * src2)) : LINEAR_DODGE(src1,(2 * (src2 - 128)))
BVBLEND_VIVID_LIGHT  (src2 &lt; 128) ? COLOR_BURN(src1,(2 * src2)) : COLOR_DODGE(src1,(2 * (src2 - 128))))
BVBLEND_PIN_LIGHT    (src2 &lt; 128) ? DARKEN(src1,(2 * src2)) : LIGHTEN(src1,(2 * (src2 - 128)))
BVBLEND_HARD_MIX     (VIVID_LIGHT(src1, src2) &lt; 128) ? 0 : 255
BVBLEND_REFLECT      (src2 == 255) ? src2 : min(255, (src1 * src1 / (255 - src2)))
BVBLEND_GLOW         (src1 == 255) ? src1 : min(255, (src2 * src2 / (255 - src1)))
BVBLEND_PHOENIX      min(src1, src2) - max(src1, src2) + 255)
BVBLEND_ALPHA        alf * src1 + (1 - alf) * src2)</code></pre>
		</td>
	</tr>
</table>
<a name="filter" class="Code_Header_2">bvbltparams.op.filter</a>
<p class="code_block">struct bvfilter *filter; /* input */</p>
<p>When <span class="inline_code"><a href="#BVFLAG_FILTER">BVFLAG_FILTER</a></span> is set in the
<span class="inline_code"><a href="#flags">bvbltparams.flags</a></span> member, the <span class="inline_code">
<a href="#op">bvbltparams.op</a></span> union is treated as a <span class="inline_code">filter</span>.</p>
<p>To specify the filter, the client fills in <span class="inline_code">filter</span> with one of the
<span class="inline_code">bvfilter</span> values.</p>
<p>These values will be extended as general filter types are requested.</p>
<a name="colorkey" class="Code_Header_2">bvbltparams.colorkey</a>
<p class="code_block">void *colorkey; /* input */</p>
<p>When either <span class="inline_code"><a href="#BVFLAG_KEY_SRC">BVFLAG_KEY_SRC</a></span> or
<span class="inline_code"><a href="#BVFLAG_KEY_DST">BVFLAG_KEY_DST</a></span> is set in the <span class="inline_code">
<a href="#flags">bvbltparams.flags</a></span> member, <span class="inline_code">colorkey</span> points to a single pixel 
used as the color key.</p>
<p>The format of this pixel matches the surface being keyed.&nbsp; i.e. <span class="inline_code"><a href="#bvsurfgeom">
src1geom.format</a></span> is the format of the color key if <span class="inline_code">BVFLAG_KEY_SRC</span> is set, or
<span class="inline_code"><a href="#bvsurfgeom">dst.format</a></span> is the format of the color key if
<span class="inline_code">BVFLAG_KEY_DST</span> is set.</p>
<p><em>Subsampled formats do not currently support color keying.</em></p>
<p class="Code_Header_2"><a name="globalalpha">bvbltparams.globalalpha</a></p>
<p class="code_block">union bvalpha globalalpha; /* input */</p>
<p>When <span class="inline_code"><a href="#BVFLAG_BLEND">BVFLAG_BLEND</a></span> is set in the
<span class="inline_code"><a href="#flags">bvbltparams.flags</a></span>, and when the <span class="inline_code">
<a href="#blend">blend</a></span> chosen requires it, <span class="inline_code">globalalpha</span> is used to provide an 
alpha blending value for the entire operation.&nbsp; The type is also dependent on the <span class="inline_code">
<a href="#blend">blend</a></span> chosen.</p>
<p>For the <span class="inline_code">BVBLENDDEF_FORMAT_CLASSIC</span> blend types, if the <span class="inline_code">BVBLENDDEF_GLOBAL_MASK</span> 
field is not 0, this field is used.&nbsp; Currently <span class="inline_code">BVBLENDDEF_FORMAT_CLASSIC</span> provides 
for an 8-bit (unsigned character / byte) format designated by <span class="inline_code">BVBLENDDEF_GLOBAL_UCHAR</span> as 
well as a 32-bit floating point format designated by <span class="inline_code">BVBLENDDEF_GLOBAL_FLOAT</span>.</p>
<p class="Code_Header_2"><a name="scalemode">bvbltparams.scalemode</a></p>
<p class="code_block">enum bvscalemode scalemode; /* input/output */</p>
<p>This member allows the client to specify the type of scaling to be used.&nbsp; The enumeration begins with 8 bits indicating 
the vendor.&nbsp; The remaining bits are defined by the vendor.&nbsp; <span class="inline_code">BVSCALEDEF_VENDOR_ALL</span> 
and <span class="inline_code">BVSCALEDEF_VENDOR_GENERAL</span> are shared by all implementations.</p>
<p><span class="inline_code">BVSCALEDEF_VENDOR_ALL</span> can be used to specify an implicit scale type.&nbsp; This type 
is converted to an explicit type by the implementation:</p>
<table class="indent">
	<tr>
		<td class="inline_code">BVSCALE_FASTEST</td>
		<td>The fastest method of scaling available is used.&nbsp; This may include nearest neighbor.&nbsp; The value of 
		this enumeration is purposely 0, and is the default scale type.&nbsp; No implementation will return an error for 
		this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_FASTEST_NOT_NEAREST_NEIGHBOR</td>
		<td>The fastest method of scaling available that is not nearest neighbor is used.&nbsp; This may include an alternative 
		point sample technique.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_FASTEST_POINT_SAMPLE</td>
		<td>The fastest method of scaling using a point sample technique.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_FASTEST_INTERPOLATED</td>
		<td>The fastest method of scaling using an interpolation technique.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_FASTEST_PHOTO</td>
		<td>The fastest method of scaling appropriate for photographs is used.&nbsp; This may include nearest neighbor.&nbsp; 
		No implementation will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_FASTEST_DRAWING</td>
		<td>The fastest method of scaling appropriate for drawings is used.&nbsp; This may include nearest neighbor.&nbsp; 
		No implementation will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_GOOD</td>
		<td>A scaling technique is chosen that may be higher quality than the <span class="inline_code">BVSCALE_FASTEST</span> 
		choice.&nbsp; This may include nearest neighbor.&nbsp; No implementation will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_GOOD_POINT_SAMPLE</td>
		<td>A point sample scaling technique is chosen that may be higher quality than the <span class="inline_code">BVSCALE_FASTEST_POINT_SAMPLE</span> 
		choice.&nbsp; This may include nearest neighbor.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_GOOD_INTERPOLATED</td>
		<td>An interpolated scaling technique is chosen that may be higher quality than the <span class="inline_code">BVSCALE_FASTEST_INTERPOLATED</span> 
		choice.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_GOOD_PHOTO</td>
		<td>A scaling technique appropriate for photographs is chosen that may be higher quality than the
		<span class="inline_code">BVSCALE_FASTEST_PHOTO</span> choice.&nbsp; This may include nearest neighbor.&nbsp; No 
		implementation will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_GOOD_DRAWING</td>
		<td>A scaling technique appropriate for drawings is chosen that may be higher quality than the
		<span class="inline_code">BVSCALE_FASTEST_DRAWING</span> choice.&nbsp; This may include nearest neighbor.&nbsp; 
		No implementation will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_BETTER</td>
		<td>A scaling technique is chosen that may be higher quality than the <span class="inline_code">BVSCALE_GOOD</span> 
		choice.&nbsp; This may include nearest neighbor.&nbsp; No implementation will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_BETTER_POINT_SAMPLE</td>
		<td>A point sample scaling technique is chosen that may be higher quality than the <span class="inline_code">BVSCALE_GOOD_POINT_SAMPLE</span> 
		choice.&nbsp; This may include nearest neighbor.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_BETTER_INTERPOLATED</td>
		<td>An interpolated scaling technique is chosen that may be higher quality than the <span class="inline_code">BVSCALE_GOOD_INTERPOLATED</span> 
		choice.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_BETTER_PHOTO</td>
		<td>A scaling technique appropriate for photographs is chosen that may be higher quality than the
		<span class="inline_code">BVSCALE_GOOD_PHOTO</span> choice.&nbsp; This may include nearest neighbor.&nbsp; No implementation 
		will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_BETTER_DRAWING</td>
		<td>A scaling technique appropriate for drawings is chosen that may be higher quality than the
		<span class="inline_code">BVSCALE_GOOD_DRAWING</span> choice.&nbsp; This may include nearest neighbor.&nbsp; No 
		implementation will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_BEST</td>
		<td>The highest quality scaling technique is chosen.&nbsp; This may include nearest neighbor.&nbsp; No implementation 
		will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_BEST_POINT_SAMPLE</td>
		<td>The highest quality point sample technique is chosen.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_BEST_INTERPOLATED</td>
		<td>The highest quality interpolated scaling technique is chosen.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_BEST_PHOTO</td>
		<td>The highest quality scaling technique appropriate for photographs is chosen.&nbsp; This may include nearest 
		neighbor.&nbsp; No implementation will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_BEST_DRAWING</td>
		<td>The highest quality scaling technique appropriate for drawings is chosen.&nbsp; This may include nearest neighbor.&nbsp; 
		No implementation will return an error for this setting.</td>
	</tr>
</table>
<br />
<span class="inline_code">BVSCALEDEF_VENDOR_GENERAL</span> can be used to specify one of the shared explicit scale types.&nbsp; 
At this point, only a limited number of explicit scale types are defined: <br />
<br />
<table class="indent">
	<tr>
		<td class="inline_code">BVSCALE_NEAREST_NEIGHBOR</td>
		<td>This is a point sample scaling technique where the resampled destination pixel is set to the value of the closest 
		source pixel.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_BILINEAR</td>
		<td>This is an interpolated scaling technique where the resampled destination pixel is set to a value linearly interpolated 
		in two dimensions from the four closest source pixels.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_BICUBIC</td>
		<td>This is an interpolated scaling technique where the resampled destination pixel is set to a value calculated 
		using cubic interpolation in two dimensions.</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_3x3_TAP</td>
		<td>&nbsp;</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_5x5_TAP</td>
		<td>&nbsp;</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_7x7_TAP</td>
		<td>&nbsp;</td>
	</tr>
	<tr>
		<td class="inline_code">BVSCALE_9x9_TAP</td>
		<td>&nbsp;</td>
	</tr>
</table>
<p>If the client wants to know the explicit type chosen by a given implementation, it can set <span class="inline_code">
BVFLAG_SCALE_RETURN</span> in the <span class="inline_code"><a href="#flags">bvbltparams.flags</a></span> member, and the 
explicit scale type is returned in the <span class="inline_code">scalemode</span> member.</p>
<p class="note">NOTE:&nbsp; Extending the <span class="inline_code">BVSCALEDEF_VENDOR_GENERAL</span> scale types or obtaining 
a vendor ID can be accomplished by submitting a patch.</p>
<p class="Code_Header_2"><a name="dithermode">bvbltparams.dithermode</a></p>
<p class="code_block">enum bvdithermode dithermode; /* input/output */</p>
<p>This member allows the client to specify the type of dithering to be used, when the output format has fewer bits of depth 
than the internal calculation.&nbsp; The enumeration begins with 8 bits indicating the vendor.&nbsp; The remaining bits 
are defined by the vendor.&nbsp; <span class="inline_code">BVDITHERDEF_VENDOR_ALL</span> and <span class="inline_code">BVDITHERDEF_VENDOR_GENERAL</span> 
are shared by all implementations.</p>
<p><span class="inline_code">BVDITHERDEF_VENDOR_ALL</span> can be used to specify an implicit dither type.&nbsp; This type 
is converted to an explicit type by the implementation:</p>
<table class="indent">
	<tr>
		<td class="inline_code">BVDITHER_FASTEST</td>
		<td>The fastest method of dithering available is used.&nbsp; This may include no dithering (truncation).&nbsp; The 
		value of this enumeration is purposely 0, and is the default dither type.&nbsp; No implementation will return an 
		error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_FASTEST_ON</td>
		<td>The fastest method of dithering available is used.&nbsp; This will not include no dithering.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_FASTEST_RANDOM</td>
		<td>The fastest method of dithering using a random technique.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_FASTEST_ORDERED</td>
		<td>The fastest method of dithering using an ordered diffusion technique.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_FASTEST_DIFFUSED</td>
		<td>The fastest method of dithering using an error diffusion technique.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_FASTEST_PHOTO</td>
		<td>The fastest method of dithering appropriate for photographs is used.&nbsp; This may include no dithering.&nbsp; 
		No implementation will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_FASTEST_DRAWING</td>
		<td>The fastest method of dithering appropriate for drawings is used.&nbsp; This may include no dithering.&nbsp; 
		No implementation will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_GOOD</td>
		<td>A dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_FASTEST</span> 
		choice.&nbsp; This may include no dithering.&nbsp; No implementation will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_GOOD_ON</td>
		<td>Any dithering technique available is used.&nbsp; This will not include no dithering.&nbsp; This may be higher 
		quality than <span class="inline_code">BVDITHER_FASTEST_ON</span>.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_GOOD_RANDOM</td>
		<td>A random dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_FASTEST_RANDOM</span> 
		choice.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_GOOD_ORDERED</td>
		<td>An ordered dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_FASTEST_ORDERED</span> 
		choice.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_GOOD_DIFFUSED</td>
		<td>A diffused dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_FASTEST_DIFFUSED</span> 
		choice.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_GOOD_PHOTO</td>
		<td>A dithering technique appropriate for photographs is chosen that may be higher quality than the
		<span class="inline_code">BVDITHER_FASTEST_PHOTO</span> choice.&nbsp; This may include no dithering.&nbsp; No implementation 
		will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_GOOD_DRAWING</td>
		<td>A dithering technique appropriate for drawings is chosen that may be higher quality than the
		<span class="inline_code">BVDITHER_FASTEST_DRAWING</span> choice.&nbsp; This may include no dithering.&nbsp; No 
		implementation will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_BETTER</td>
		<td>A dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_GOOD</span> 
		choice.&nbsp; This may include no dithering.&nbsp; No implementation will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_BETTER_ON</td>
		<td>Any dithering technique available is used.&nbsp; This will not include no dithering.&nbsp; This may be higher 
		quality than <span class="inline_code">BVDITHER_GOOD_ON</span>.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_BETTER_RANDOM</td>
		<td>A random dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_GOOD_RANDOM</span> 
		choice.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_BETTER_ORDERED</td>
		<td>An ordered dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_GOOD_ORDERED</span> 
		choice.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_BETTER_DIFFUSED</td>
		<td>A diffused dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_GOOD_DIFFUSED</span> 
		choice.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_BETTER_PHOTO</td>
		<td>A scaling technique appropriate for photographs is chosen that may be higher quality than the
		<span class="inline_code">BVSCALE_GOOD_PHOTO</span> choice.&nbsp; No implementation will return an error for this 
		setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_BETTER_DRAWING</td>
		<td>A scaling technique appropriate for drawings is chosen that may be higher quality than the
		<span class="inline_code">BVSCALE_GOOD_DRAWING</span> choice.&nbsp; No implementation will return an error for this 
		setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_BEST</td>
		<td>The highest quality dithering technique is chosen.&nbsp; This may include no dithering.&nbsp; No implementation 
		will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_BEST_ON</td>
		<td>Any dithering technique available is used.&nbsp; This will not include no dithering.&nbsp; This may be higher 
		quality than <span class="inline_code">BVDITHER_BEST_ON</span>.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_BEST_RANDOM</td>
		<td>The highest quality random dithering technique is chosen.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_BEST_ORDERED</td>
		<td>The highest quality ordered dithering technique is chosen.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_BEST_DIFFUSED</td>
		<td>The highest quality diffused dithering technique is chosen.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_BEST_PHOTO</td>
		<td>The highest quality dithering technique appropriate for photographs is chosen.&nbsp; This may include no dithering.&nbsp; 
		No implementation will return an error for this setting.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_BEST_DRAWING</td>
		<td>The highest quality dithering technique appropriate for drawings is chosen.&nbsp; This may include no dithering.&nbsp; 
		No implementation will return an error for this setting.</td>
	</tr>
</table>
<br />
<span class="inline_code">BVDITHERDEF_VENDOR_GENERAL</span> can be used to specify one of the shared explicit dithering 
types.&nbsp; At this point, only a limited number of explicit dither types are defined:<br />
<br />
<table class="indent">
	<tr>
		<td class="inline_code">BVDITHER_NONE</td>
		<td>No dithering is performed.&nbsp; Internal pixel component values are truncated to the destination component 
		bit depth.</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_ORDERED_2x2</td>
		<td>&nbsp;</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_ORDERED_4x4</td>
		<td>&nbsp;</td>
	</tr>
	<tr>
		<td class="inline_code">BVDITHER_ORDERED_2x2_4x4</td>
		<td>2x2 ordered dither is used for components with the lowest bit reduction.&nbsp; 4x4 ordered dither is used for 
		the components with the highest bit reduction.&nbsp; (E.g. RGB24 to RGB565 will use 2x2 ordered dither for the green 
		component and 4x4 ordered dither for the red and blue components.)</td>
	</tr>
</table>
<p>If the client wants to know the explicit type chosen by a given implementation, it can set <span class="inline_code">
BVFLAG_DITHER_RETURN</span> in the <span class="inline_code"><a href="#flags">bvbltparams.flags</a></span> member, and the 
explicit scale type is returned in the <span class="inline_code">dithermode</span> member.</p>
<p class="note">NOTE:&nbsp; Extending the <span class="inline_code">BVDITHERDEF_VENDOR_GENERAL</span> scale types or obtaining 
a vendor ID can be accomplished by submitting a patch.</p>
<p class="Code_Header_2"><a name="dstdesc">bvbltparams.dstdesc</a></p>
<p class="code_block"><a href="#bvbuffdesc">struct bvbuffdesc</a> *dstdesc;</p>
<p><span class="inline_code">dstdesc</span> is used to specify the destination buffer.&nbsp; If the buffer has not been 
mapped with a call to <span class="inline_code"><a href="#bv_map">bv_map()</a></span>, <span class="inline_code">
<a href="#bv_blt">bv_blt()</a></span> will map the buffer as necessary to perform the BLT and then unmap afterwards.&nbsp; 
See <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> for details.</p>
<p class="Code_Header_2"><a name="dstgeom">bvbltparams.dstgeom</a></p>
<p class="code_block"><a href="#bvsurfgeom">struct bvsurfgeom</a> *dstgeom;</p>
<p><span class="inline_code">dstgeom</span> is used to specify the geometry of the surface contained in the destination 
buffer.&nbsp; See <span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> for details.</p>
<p class="Code_Header_2"><a name="dstrect">bvbltparams.dstrect</a></p>
<p class="code_block"><a href="#bvrect">struct bvrect</a> dstrect;</p>
<p><span class="inline_code">dstrect</span> is used to specify the destination rectangle to receive the BLT.&nbsp; This 
rectangle is clipped by <span class="inline_code"><a href="#cliprect">bvbltparams.cliprect</a></span> when
<span class="inline_code"><a href="#BVFLAG_CLIP">BVFLAG_CLIP</a></span> is set in the <span class="inline_code">
<a href="#flags">bvbltparams.flags</a></span> member.</p>
<p class="Code_Header_2">bvbltparams.<a name="src1.desc">src1</a>/<a name="src2.desc">src2</a>/<a name="mask.desc">mask.desc</a></p>
<p class="code_block"><a href="#bvbuffdesc">struct bvbuffdesc</a> *src1.desc;<br />
<a href="#bvbuffdesc">struct bvbuffdesc</a> *src2.desc;<br />
<a href="#bvbuffdesc">struct bvbuffdesc</a> *mask.desc;</p>
<p>These members are used to identify the buffer for the source1, source2, and mask surfaces when the associated
<span class="inline_code">BVFLAG_TILE_*</span> flag is not set.&nbsp; The buffer is the memory in which the surface lies.&nbsp; 
See the <span class="inline_code"><a href="#src1geom">bvbltparams.src1/src2/maskgeom</a></span> for the format and layout/geometry 
of the surface.</p>
<p class="note">NOTE WELL:&nbsp; Clients should never change the value of a <span class="inline_code">
<a href="#bvbuffdesc">bvbuffdesc</a></span> structure while a buffer is mapped.</p>
<p class="Code_Header_2">bvbltparams.<a name="src1.tileparams">src1</a>/<a name="src2.tileparams">src2</a>/<a name="mask.tileparams">mask.tileparams</a></p>
<p class="code_block"><a href="#bvtileparams">struct bvtileparams</a> *src1.tileparams;<br />
<a href="#bvtileparams">struct bvtileparams</a> *src2.tileparams;<br />
<a href="#bvtileparams">struct bvtileparams</a> *mask.tileparams;</p>
<p>These members are used to identify the buffer for the source1, source2, and mask surfaces when the associated
<span class="inline_code">BVFLAG_TILE_*</span> flag is set.&nbsp; The buffer is the memory in which the surface lies.&nbsp; 
This differs from the <span class="inline_code"><a href="#src1.desc">src1/src2/mask.desc</a></span> identity by providing 
more information needed for tiling and by not requiring mapping (for hardware implementations that support tiling, the tile 
data is usually moved into an on-chip cache).</p>
<p class="Code_Header_2">bvbltparams.<a name="src1geom">src1</a>/<a name="src2geom">src2</a>/<a name="maskgeom">maskgeom</a></p>
<p class="code_block"><a href="#bvsurfgeom">struct bvsurfgeom</a> src1geom;<br />
<a href="#bvsurfgeom">struct bvsurfgeom</a> src2geom;<br />
<a href="#bvsurfgeom">struct bvsurfgeom</a> maskgeom;</p>
<p>These members describe the format and layout/geometry of their respective surfaces.&nbsp; Separating
<span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> from the <span class="inline_code">
<a href="#bvbuffdesc">bvbuffdesc</a></span> allows easy use of buffers for multiple geometries without remapping.&nbsp; 
See <span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> and <span class="inline_code">
<a href="#bvbuffdesc">bvbuffdesc</a></span> for details.</p>
<p class="Code_Header_2">bbvbltparams.src1/src2/maskrect</p>
<p class="code_block"><a href="#bvrect">struct bvrect</a> src1rect;<br />
<a href="#bvrect">struct bvrect</a> src2rect;<br />
<a href="#bvrect">struct bvrect</a> maskrect;</p>
<p>These members specify the rectangle from which data is read for the BLT.&nbsp; These rectangles are clipped by a scaled 
version of the <span class="inline_code"><a href="#cliprect">bvbltparams.cliprect</a></span>&nbsp; (scaling is based on 
the relationship between them and the <span class="inline_code"><a href="#dstrect">bvbltparams.dstrect</a></span>) when
<span class="inline_code"><a href="#BVFLAG_CLIP">BVFLAG_CLIP</a></span> is set in the <span class="inline_code">
<a href="#flags">bvbltparams.flags</a></span> member.</p>
<table class="example">
	<tr>
		<td>
		<p><strong>Example:</strong></p>
		<a href="#src1rect" class="inline_code">src1rect</a> = (0, 0) - (400 x 200)<br />
		<a href="#dstrect" class="inline_code">dstrect</a> = (0, 0) - (800 x 600)<br />
		<a href="#cliprect" class="inline_code">cliprect</a> = (10, 30) - (300 x 300)<p>The scaling ratio of the
		<a href="#dstrect" class="inline_code">dstrect</a> to the <a href="#src1rect" class="inline_code">src1rect</a> is 
		(800/400,&nbsp; 600/300) or (2, 3).&nbsp; Using this, the effective source 1 clipping rectangle becomes (10/2, 30/3) 
		- (300/2 x 300/3) or (5, 10) - (150 x 100).</p>
		</td>
	</tr>
</table>
<p>This approach allows fractional clipping at the source using a method which is simpler to implement than fractional coordinates.</p>
<p class="note">NOTE:&nbsp; In BLTsville, reading outside the source rectangle is forbidden.&nbsp; So scaling algorithms 
which require pixels around a particular source pixel must utilize boundary techniques (mirror, repeat, clamp, etc.) at 
the edges of the source rectangle.&nbsp; However, if the clipping rectangle, when translated back to the source rectangle, 
leaves space between it and the source rectangle, pixels outside the clipped region may be accessed by the implementation.</p>
<p class="Code_Header_2"><a name="cliprect">bvbltparams.cliprect</a></p>
<p class="code_block"><a href="#bvrect">struct bvrect</a> cliprect;</p>
<p><span class="inline_code">cliprect</span> is used to specify a rectangle that limits what region of the destination is 
written.&nbsp; This is most useful for scaling operations, where the necessary scaling factor will not allow translation 
of the destination rectangle back to the source on an integer pixel boundary.</p>
<p class="note">NOTE:&nbsp; If <span class="inline_code">cliprect</span> exceeds the destination surface, the behavior is 
undefined. </p>
<p>For example, if the goal is to show a 640 x 480 video on a 1920 x 1080 screen, the video would be stretched to 1440 x 
1080 to maintain the proper aspect ratio.&nbsp; So the relevant rectangles would be:</p>
<table class="indent">
	<tr>
		<td class="thin_bord"><strong>src1rect</strong></td>
		<td class="thin_bord"><strong>dstrect</strong></td>
	</tr>
	<tr>
		<td class="thin_bord">(0, 0) - 640 x 480</td>
		<td class="thin_bord">(240, 0) - 1440 x 1080</td>
	</tr>
</table>
<p>However, to handle a 640 x 480 pop-up window that appears centered on the screen, in front of the video, the single BLT 
may be broken into four smaller BLTs pieced around the popup.&nbsp; These rectangles would need to be:</p>
<table class="indent">
	<tr>
		<td class="thin_bord"><strong>src1rect</strong></td>
		<td class="thin_bord"><strong>dstrect</strong></td>
	</tr>
	<tr>
		<td class="thin_bord">(0, 0) - 640 x 133.333...</td>
		<td class="thin_bord">(240, 0) - 1440 x 300</td>
	</tr>
	<tr>
		<td class="thin_bord">(0, 133.333...) - 284.444... x 213.333...</td>
		<td class="thin_bord">(240, 300) - 400 x 480</td>
	</tr>
	<tr>
		<td class="thin_bord">(568.888..., 133.333...) - 284.444... x 213.333...</td>
		<td class="thin_bord">(1280, 300) - 400 x 480</td>
	</tr>
	<tr>
		<td class="thin_bord">(0, 346.666...) - 640 x 133.333...</td>
		<td class="thin_bord">(240, 780) - 1440 x 300</td>
	</tr>
</table>
<p>Since this is a scaling factor of 2.25x, translating the required destination rectangles back to the source results in 
non-integer coordinates and dimensions, as illustrated above.&nbsp; And adjusting the source rectangles to the nearest integer 
values will result in visible discontinuities at the boundaries between the rectangles.</p>
<p>Instead, using the <span class="inline_code">cliprect</span>, this situation can be handled more easily:</p>
<table class="indent">
	<tr>
		<td class="thin_bord"><strong>src1rect</strong></td>
		<td class="thin_bord"><strong>dstrect</strong></td>
		<td class="thin_bord"><strong>cliprect</strong></td>
	</tr>
	<tr>
		<td class="thin_bord">(0, 0) - 640 x 480</td>
		<td class="thin_bord">(240, 0) - 1440 x 1080</td>
		<td class="thin_bord">(240, 0) - 1440 x 300</td>
	</tr>
	<tr>
		<td class="thin_bord">(0, 0) - 640 x 480</td>
		<td class="thin_bord">(240, 0) - 1440 x 1080</td>
		<td class="thin_bord">(240, 300) - 400 x 480</td>
	</tr>
	<tr>
		<td class="thin_bord">(0, 0) - 640 x 480</td>
		<td class="thin_bord">(240, 0) - 1440 x 1080</td>
		<td class="thin_bord">(1280, 300) - 400 x 480</td>
	</tr>
	<tr>
		<td class="thin_bord">(0, 0) - 640 x 480</td>
		<td class="thin_bord">(240, 0) - 1440 x 1080</td>
		<td class="thin_bord">(240, 780) - 1440 x 300</td>
	</tr>
</table>
<p class="Code_Header_2"><a name="batchflags">bvbltparams.batchflags</a></p>
<p class="code_block">unsigned long batchflags;</p>
<p><span class="inline_code">batchflags</span> are used by the client as a hint to indicate to the implementation which 
parameters are changing between successive BLTs of a batch.&nbsp; The flags may be used when the
<span class="inline_code"><a href="#flags">bvbltparams.flags</a></span> has <span class="inline_code">
<a href="#BVFLAG_BATCH_CONTINUE">BVFLAG_BATCH_CONTINUE</a></span> or <span class="inline_code">
<a href="#BVFLAG_BATCH_END">BVFLAG_BATCH_END</a></span> set.</p>
<table style="" class="indent">
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_OP">BVBATCH_OP</a></span></td>
		<td>indicates that the operation type (<span class="inline_code"><a href="#BVFLAG_ROP">BVFLAG_ROP</a></span>,
		<span class="inline_code"><a href="#BVFLAG_BLEND">BVFLAG_BLEND</a></span>, <span class="inline_code">
		<a href="#BVFLAG_FILTER">BVFLAG_FILTER</a></span>, etc.) has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_KEY">BVBATCH_KEY</a></span></td>
		<td>indicates that the <span class="inline_code"><a href="#colorkey">bvbltparams.colorkey</a></span> or the color 
		key mode (<span class="inline_code"><a href="#BVFLAG_KEY_SRC">BVFLAG_KEY_SRC</a></span>/<span class="inline_code"><a href="#BVFLAG_KEY_DST">BVFLAG_KEY_DST</a></span>) 
		has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_MISCFLAGS">BVBATCH_MISCFLAGS</a></span></td>
		<td>indicates that <span class="inline_code"><a href="#flags">bvbltparams.flags</a></span> other than the operation, 
		color key, or clip flag have changes.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_ALPHA">BVBATCH_ALPHA</a></span></td>
		<td>indicates that <span class="inline_code"><a href="#globalalpha">bvbltparams.globalalpha</a></span> or global 
		alpha type has changed.</td>
	</tr>
	<tr>
		<td><a name="BVBATCH_DITHER" class="inline_code">BVBATCH_DITHER</a></td>
		<td>indicates that <span class="inline_code"><a href="#dithermode">bvbltparams.dithermode</a></span> has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_SCALE">BVBATCH_SCALE</a></span></td>
		<td>indicates that <span class="inline_code"><a href="#scalemode">bvbltparams.scalemode</a></span> has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_DST">BVBATCH_DST</a></span></td>
		<td>indicates that the destination surface (<span class="inline_code"><a href="#dstdesc">bvbltparams.dstdesc</a></span>,
		<span class="inline_code"><a href="#dstgeom">bvbltparams.dstgeom</a></span> ,or <span class="inline_code">
		<a href="#dstrect">bvbltparams.dstrect</a></span>) has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_SRC1">BVBATCH_SRC1</a></span> </td>
		<td>indicates that the source 1 surface (<span class="inline_code"><a href="#src1.desc">bvbltparams.src1.desc</a></span> 
		or <span class="inline_code"><a href="#src1.tileparams">bvbltparams.src1.tileparams</a></span>, or
		<span class="inline_code"><a href="#src1geom">bvbltparams.src1geom</a></span>) has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_SRC2">BVBATCH_SRC2</a></span> </td>
		<td>indicates that the source 2 surface (<span class="inline_code"><a href="#src2.desc">bvbltparams.src2.desc</a></span> 
		or <span class="inline_code"><a href="#src2.tileparams">bvbltparams.src2.tileparams</a></span>, or
		<span class="inline_code"><a href="#src2geom">bvbltparams.src2geom</a></span>) has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_MASK">BVBATCH_MASK</a></span> </td>
		<td>indicates that the mask surface (<span class="inline_code"><a href="#mask.desc">bvbltparams.mask.desc</a></span> 
		or <span class="inline_code"><a href="#mask.tileparams">bvbltparams.mask.tileparams</a></span>, or
		<span class="inline_code"><a href="#maskgeom">bvbltparams.maskgeom</a></span>) has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_DSTRECT_ORIGIN">BVBATCH_DSTRECT_ORIGIN</a></span></td>
		<td>indicates that <span class="inline_code"><a href="#dstrect">bvbltparams.dstrect.left</a></span> or
		<span class="inline_code"><a href="#dstrect">top</a></span> has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_DSTRECT_SIZE">BVBATCH_DSTRECT_SIZE</a></span></td>
		<td>indicates that the <span class="inline_code"><a href="#dstrect">bvbltparams.dstrect.width</a></span> or
		<a href="#dstrect">height</a> has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_SRC1RECT_ORIGIN">BVBATCH_SRC1RECT_ORIGIN</a></span></td>
		<td>indicates that <span class="inline_code"><a href="#src1rect">bvbltparams.src1rect.left</a></span> or
		<span class="inline_code"><a href="#dstrect">top</a></span> has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_SRC1RECT_SIZE">BVBATCH_SRC1RECT_SIZE</a></span></td>
		<td>indicates that the <span class="inline_code"><a href="#src1rect">bvbltparams.src1rect.width</a></span> or
		<a href="#src1rect">height</a> has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_SRC2RECT_ORIGIN">BVBATCH_SRC2RECT_ORIGIN</a></span></td>
		<td>indicates that <span class="inline_code"><a href="#src2rect">bvbltparams.src2rect.left</a></span> or
		<span class="inline_code"><a href="#src2rect">top</a></span> has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_SRC2RECT_SIZE">BVBATCH_SRC2RECT_SIZE</a></span></td>
		<td>indicates that the <span class="inline_code"><a href="#src2rect">bvbltparams.src2rect.width</a></span> or
		<a href="#src2rect">height</a> has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_MASKRECT_ORIGIN">BVBATCH_MASKRECT_ORIGIN</a></span></td>
		<td>indicates that <span class="inline_code"><a href="#maskrect">bvbltparams.maskrect.left</a></span> or
		<span class="inline_code"><a href="#maskrect">top</a></span> has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_MASKRECT_SIZE">BVBATCH_MASKRECT_SIZE</a></span></td>
		<td>indicates that the <span class="inline_code"><a href="#maskrect">bvbltparams.maskrect.width</a></span> or
		<a href="#maskrect">height</a> has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_CLIPRECT_ORIGIN">BVBATCH_CLIPRECT_ORIGIN</a></span></td>
		<td>indicates that <span class="inline_code"><a href="#cliprect">bvbltparams.cliprect.left</a></span> or
		<span class="inline_code"><a href="#cliprect">top</a></span> has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_CLIPRECT_SIZE">BVBATCH_CLIPRECT_SIZE</a></span></td>
		<td>indicates that the <span class="inline_code"><a href="#cliprect">bvbltparams.cliprect.width</a></span> or
		<a href="#cliprect">height</a> has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_TILE_SRC1">BVBATCH_TILE_SRC1</a></span></td>
		<td>indicates that the <span class="inline_code"><a href="#src1.tileparams">bvbltparams.src1.tileparams</a></span> 
		has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_TILE_SRC2">BVBATCH_TILE_SRC2</a></span></td>
		<td>indicates that the <span class="inline_code"><a href="#src2.tileparams">bvbltparams.src2.tileparams</a></span> 
		has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_TILE_MASK">BVBATCH_TILE_MASK</a></span></td>
		<td>indicates that the <span class="inline_code"><a href="#mask.tileparams">bvbltparams.mask.tileparams</a></span> 
		has changed.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVBATCH_ENDNOP">BVBATCH_ENDNOP</a></span></td>
		<td>is a special flag used with <span class="inline_code"><a href="#batch_end">BVFLAG_BATCH_END</a></span>, for 
		clients that do not have information that a batch is ending until after the last BLT has been issued.&nbsp; When 
		this flag is set, no BLT is done, but the batch is ended.</td>
	</tr>
</table>
<p class="note">NOTE:&nbsp; These flags are hints, and may be used or not by a BLTsville implementation.&nbsp; So if
<span class="inline_code"><a href="#bvbltparams">bvbltparams</a></span> members are changed between BLTs in a batch, but 
the <span class="inline_code">bvbltparams.batchflags</span> member is not correctly updated, the resulting behavior on different 
implementations will not be consistent.</p>
<p class="Code_Header_2"><a name="batch">bvbltparams.batch</a></p>
<p class="code_block"><a href="#bvbatch">struct bvbatch</a> *batch;</p>
<p>This member is used as a batch handle, so that multiple batches can be under construction at the same time.</p>
<p class="Code_Header_2"><a name="callbackfn">bvbltparams.callbackfn</a></p>
<p class="code_block">void (*callbackfn)(<a href="#bvcallbackerror">struct bvcallbackerror</a> *err, unsigned long
<a href="#callbackdata">callbackdata</a>);</p>
<p>This member is a pointer to a client-supplied function which is called by the implementation when
<span class="inline_code"><a href="#BVFLAG_ASYNC">BVFLAG_ASYNC</a></span> is set and the BLT is complete.&nbsp; If this 
member is NULL, no callback is performed.&nbsp; When there is no error, the <span class="inline_code">err</span> 
parameter will be set to 0;</p>
<p class="note">NOTE:&nbsp; This function <span class="underline">can be called</span> before the
<span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> call has returned.</p>
<p class="Code_Header_2"><a name="callbackdata">bvbltparams.callbackdata</a></p>
<p class="code_block">unsigned long callbackdata;</p>
<p>This member is used as the parameter passed back by the <span class="inline_code"><a href="#callbackfn">bvbltparams.callbackfn</a></span>.&nbsp; 
This can be anything from an identifying index to a pointer used by the client.</p>
<p class="Code_Header_2">bvbltparams.<a name="src2auxdstrect">src2</a>/<a name="maskauxdstrect">maskauxdstrect</a></p>
<p class="code_block">struct bvrect src2auxdstrect;<br />
struct bvrect maskauxdstrect;</p>
<p>These two members are used only when the associated <span class="inline_code"><a href="#BVFLAG_SRC2_AUXDSTRECT">
BVFLAG_SRC2</a></span>/<span class="inline_code"><a href="#BVFLAG_MASK_AUXDSTRECT">MASK_AUXDSTRECT</a></span> flags are 
set.&nbsp; They are only necessary (and should only be used) in the case where scaling of the inputs differs and the 
entire source images are not being used.&nbsp; <span class="inline_code"><a href="#dstrect">bvbltparams.dstrect</a></span> is always 
used to specify the destination of source 1 image.&nbsp; When the associated flags are set, these two members are used 
to specify the destination of the source 2 and mask images, instead of <span class="inline_code"><a href="#dstrect">
bvbltparams.dstrect</a></span>.</p>
<p>These flags must be used with the <span class="inline_code"><a href="#BVFLAG_CLIP">BVFLAG_CLIP</a></span> flag.&nbsp; 
And if the resulting clipped destination does not include all enabled destination rectangles, the results are undefined.</p>
<div class="example"><strong>Example:</strong>&nbsp; We have two images that we want to merge and view on an 854x480 LCD panel.&nbsp; One 
image is a small background image with 16:9 (64x36) aspect ratio that we want to stretch to fill the screen.&nbsp; 
The other is a standard definition 720x480 (4:3 aspect ratio) image with transparency we want to blend on top of our 
background.<br />
<table align="center">
	<tr>
		<td>
			<table>
				<tr>
					<td class="ctr"><img alt="" src="concrete-64x36.png" width="64" height="36" /></td>
				</tr>
				<tr>
					<td class="ctr">(shown actual size)</td>
				</tr>
			</table>
		</td>
		<td>
			<table class="ctr">
				<tr>
					<td><img alt="" src="clock-720x480_4x3-fauxtrans.jpg" width="360" height="240" /></td>
				</tr>
				<tr>
					<td class="ctr">(shown 1/2x; not adjusted for aspect ratio)</td>
				</tr>
			</table>
		</td>
	</tr>
</table>
We want to blend the second image onto the center of the first, scaling both, so that it looks like this:<br />
<table align="center">
	<tr>
		<td><img alt="" src="blend-854x480.jpg" width="427" height="240" /></td>
	</tr>
	<tr>
		<td class="ctr">(shown 1/2x)</td>
	</tr>
</table>
The screen is effectively a 16:9 aspect ratio (we can ignore the fraction of a pixel here), which matches our 
background image.&nbsp; So the background image just needs to be scaled from 64x36 to 854x480.<br />
<br />
	However, since the second image has a 4:3 aspect ratio, it will not cover the entire background image if we want to 
	maintain its aspect ratio.&nbsp; Our second image is not as wide as our 16:9 image, which means it&#39;s height will match 
	the screen height, but the width will be smaller.&nbsp; Since the screen is 480 lines (pixels) high, to maintain our 4:3 
	aspect ratio, our second image will need to be 640 pixels wide (4 * 480 / 3).&nbsp; So it will need to be scaled from 
	720x480 to 640x480.<br />
<br />
As we mentioned, we would like to center the 640 pixel image on our 854 pixel wide screen.&nbsp; That means the left edge 
of the image will be at pixel 107 ( (854 - 640) / 2 ).&nbsp; So the leftmost 107 columns of pixels will just be a copy 
of the left portion of the background image.&nbsp; Likewise, the rightmost 107 columns will be a copy of the right 
portion of the background image.&nbsp; Only the middle section should be blended.<br />
<table align="center">
	<tr>
		<td><img alt="" src="blend-854x480-threeblts.jpg" width="427" height="240" /></td>
	</tr>
	<tr>
		<td class="ctr">(shown 1/2x)</td>
	</tr>
</table>
	The side two BLTs are quite easy with BLTsville, by using the clipping rectangle:<br />
<br />
<table class="indent"><tr><td>
<span class="inline_code">bvbltparams.flags = BVFLAG_ROP | BVFLAG_CLIP;<br />
bvbltparams.op.rop = 0xCCCC;<br />
<br />
bvbltparams.src1.desc = bkgnddesc;<br />
bvbltparams.src1geom = bkgndgeom;<br />
bvbltparams.src1rect.left = 0;<br />
bvbltparams.src1rect.top = 0;<br />
bvbltparams.src1width = 64;<br />
bvbltparams.src1height = 36;<br />
<br />
bvbltparams.dstdesc = screendesc;<br />
bvbltparams.dstgeom = screengeom;<br />
bvbltparams.dstrect.left = 0;<br />
bvbltparams.dstrect.top = 0;<br />
bvbltparams.dstrect.width = 854;<br />
bvbltparams.dstrect.height = 480;<br />
<br />
bvbltparams.cliprect.left = 0;<br />
bvbltparams.cliprect.top = 0;<br />
bvbltparams.cliprect.width = 107;<br />
bvbltparams.cliprect.height = 480;<br />
bv_blt(&amp;bvbltparams);<br />
<br />
bvbltparams.cliprect.left += 640;<br />
bv_blt(&amp;bvbltparams);</span></td></tr></table>
<br />
	However, if we try the same approach with the middle BLT, we run into problems:<br />
<br />
<table class="indent"><tr><td>
<span class="inline_code">bvbltparams.flags = BVFLAG_BLEND | BVFLAG_CLIP;<br />
bvbltparams.op.blend = BVBLEND_SRC1OVER;<br />
<br />
bvbltparams.src1.desc = foregnddesc;<br />
bvbltparams.src1geom = foregndgeom;<br />
bvbltparams.src1rect.left = 0;<br />
bvbltparams.src1rect.top = 0;<br />
bvbltparams.src1rect.width = 720;<br />
bvbltparams.src1rect.height = 480;<br />
<br />
bvbltparams.src2.desc = bkgnddesc;<br />
bvbltparams.src2geom = bkgndgeom;<br />
bvbltparams.src2rect.left = 0;<br />
bvbltparams.src2rect.top = 0;<br />
bvbltparams.src2width = 64;<br />
bvbltparams.src2height = 36;<br />
<br />
bvbltparams.cliprect.left = 107;<br />
bvbltparams.cliprect.top = 0;<br />
bvbltparams.cliprect.width = 640;<br />
bvbltparams.cliprect.height = 480;<br />
bv_blt(&amp;bvbltparams);</span></td></tr></table>
<table align="center">
	<tr>
		<td><img alt="" src="blend-854x480-bad.jpg" width="427" height="240" /></td>
	</tr>
	<tr>
		<td class="ctr">(shown 1/2x)</td>
	</tr>
</table>
	The result is that the foreground image is stretched horizontally.&nbsp; That&#39;s because the scaling factor is 
	derived from the source (1) rectangle and the destination rectangle, which is the full width of the screen.&nbsp; 
	Since we were also scaling the background, we set the destination rectangle to cover the screen, as we did in the 
	previous two BLTs.<br />
	<br />
	The edges of our foreground image are also cropped, since we were only modifying the middle of the screen.<br />
	<br />
	What if we change the destination rectangle?<br />
	<br />
<table class="indent"><tr><td>
<span class="inline_code">bvbltparams.dstrect.left = 107;<br />
bvbltparams.dstrect.top = 0;<br />
bvbltparams.dstrect.width = 640;<br />
bvbltparams.dstrect.height = 480;<br />
<br />
bv_blt(&amp;bvbltparams);</span></td></tr></table>
<table align="center">
	<tr>
		<td><img alt="" src="blend-854x480-bad2.jpg" width="427" height="240" /></td>
	</tr>
	<tr>
		<td class="ctr">(shown 1/2x)</td>
	</tr>
</table>
	Here we get the proper scaling of the foreground image, but the background image is scaled improperly.<br />
	<br />
	What if we adjust the source rectangles?&nbsp;
For our purposes, we want all of the foreground image, but we only need the middle of the background image.&nbsp; So 
	we can manually specify the middle of the background image by modifying the source 2 rectangle:<br />
	<br />
<table class="indent"><tr><td>
<span class="inline_code">bvbltparams.src2rect.left = 107 * 64 / 854;<br />
bvbltparams.src2rect.width = 640 * 64 / 854;</span></td></tr></table><br />
Nice, but what are those values?<br />
<br />
<table class="indent"><tr><td>
107 * 1280 / 854 = 8.0187...<br />
640 * 1280 / 854 = 47.9625...<br />
</td></tr></table>
<br />
	In BLTsville, all rectangle parameters are expressed in integers (this also allows BLTsville to be used in the 
	kernels where floating point variables are not allowed).&nbsp; The clipping rectangle then handles introducing the 
	necessary source pixel subdivision (by translating the clipping rectangle back to the source rectangle in the 
	implementation).&nbsp; So what happens if we actually do use these values as integers?<br />
<br />
<table class="indent"><tr><td>
<span class="inline_code">bvbltparams.src2rect.left = 8;<br />
bvbltparams.src2rect.top = 0;<br />
bvbltparams.src2rect.width = 47;<br />
bvbltparams.src2height = 36;<br />
<br />
bv_blt(&amp;bvbltparams);</span></td></tr></table>
<br />
	And this is what we get:<br />
<table align="center">
	<tr>
		<td><img alt="" src="blend-854x480-roundingerror.jpg" width="427" height="240" /></td>
	</tr>
	<tr>
		<td class="ctr">(shown 1/2x)</td>
	</tr>
</table>
	Closer, but not quite.&nbsp; Rounding the values above to integers still results in visible errors at the boundaries 
	between the middle and the side BLTs (the one on the right is a bit more visible at this reduced size, but if you 
	view the full image, you&#39;ll see the left one as well), because the left edge and scaling (and right edge as a 
	result) don&#39;t match the alignment and scaling done for the BLTs on the side.&nbsp; <p class="note">NOTE:&nbsp; This artifact is not always obvious in still images.&nbsp; 
	The images here were chosen to make the artifacts obvious in this documentation.&nbsp; But even if the static images 
	appear correct, movement of the images (e.g. moving the foreground image across the background image) or changes in 
	the blending (e.g. fading the foreground image out and finally removing it), will show these less obvious 
	discrepancies.</p>This is actually what the 
	clipping rectangle is for.&nbsp; It&#39;s meant to allow us to always specify the source and destination rectangles the 
	same, but move the clipping window around on the destination to get just the pixels we want.&nbsp; That way the 
	scaling and alignment area always the same.&nbsp; Unfortunately, for this special case, we really need a way to 
	specify different scaling factors for the different inputs.&nbsp; The src2auxdstrect (and maskauxdstrect, when 
	needed) have been added to provide this capability.<br />
	<br />
	Here is how this set of BLTs can be done:<br />
<br />
<table class="indent"><tr><td>
<span class="inline_code">bvbltparams.flags = BVFLAG_ROP | BVFLAG_CLIP;<br />
bvbltparams.op.rop = 0xCCCC;<br />
<br />
bvbltparams.src1.desc = bkgnddesc;<br />
bvbltparams.src1geom = bkgndgeom;<br />
bvbltparams.src1rect.left = 0;<br />
bvbltparams.src1rect.top = 0;<br />
bvbltparams.src1width = 64;<br />
bvbltparams.src1height = 36;<br />
<br />
bvbltparams.dstdesc = screendesc;<br />
bvbltparams.dstgeom = screengeom;<br />
bvbltparams.dstrect.left = 0;<br />
bvbltparams.dstrect.top = 0;<br />
bvbltparams.dstrect.width = 854;<br />
bvbltparams.dstrect.height = 480;<br />
<br />
bvbltparams.cliprect.left = 0;<br />
bvbltparams.cliprect.top = 0;<br />
bvbltparams.cliprect.width = 107;<br />
bvbltparams.cliprect.height = 480;<br />
bv_blt(&amp;bvbltparams);<br />
<br />
bvbltparams.cliprect.left += 640;<br />
bv_blt(&amp;bvbltparams);<br />
<br />
bvbltparams.flags = BVFLAG_BLEND | BVFLAG_CLIP | BVFLAG_SRC2_AUXDSTRECT;<br />
bvbltparams.op.blend = BVBLEND_SRC1OVER;<br />
<br />
bvbltparams.src1.desc = foregnddesc;<br />
bvbltparams.src1geom = foregndgeom;<br />
bvbltparams.src1rect.left = 0;<br />
bvbltparams.src1rect.top = 0;<br />
bvbltparams.src1rect.width = 720;<br />
bvbltparams.src1rect.height = 480;<br />
<br />
bvbltparams.dstrect.left = 107;<br />
bvbltparams.dstrect.top = 0;<br />
bvbltparams.dstrect.width = 640;<br />
bvbltparams.dstrect.height = 480;<br />
<br />
bvbltparams.src2.desc = bkgnddesc;<br />
bvbltparams.src2geom = bkgndgeom;<br />
bvbltparams.src2rect.left = 0;<br />
bvbltparams.src2rect.top = 0;<br />
bvbltparams.src2width = 64;<br />
bvbltparams.src2height = 36;<br />
<br />
bvbltparams.src2auxdstrect.left = 0;<br />
bvbltparams.src2auxdstrect.top = 0;<br />
bvbltparams.src2auxdstrect.width = 854;<br />
bvbltparams.src2auxdstrect.height = 480;<br />
<br />
bvbltparams.cliprect.left = 107;<br />
bvbltparams.cliprect.top = 0;<br />
bvbltparams.cliprect.width = 640;<br />
bvbltparams.cliprect.height = 480;<br />
bv_blt(&amp;bvbltparams);</span></td></tr></table>
<br />
Using this approach, we get the desired output:<br />
<table align="center">
	<tr>
		<td><img alt="" src="blend-854x480.jpg" width="427" height="240" /></td>
	</tr>
	<tr>
		<td class="ctr">(shown 1/2x)</td>
	</tr>
</table>
	It may also be clear that in that last BLT, the clip rectangle isn&#39;t really necessary.&nbsp; This is good, because 
	it frees up the clipping rectangle to be used to further subdivide the image if necessary (e.g. if partially 
	occluded).<br />
</div>
<br />
<hr />
<p class="Code_Header"><a name="bvrect">bvrect</a></p>
<p class="small_code_block">struct bvrect {<br />
&nbsp;&nbsp;&nbsp; int <a href="#bvrect.left">left</a>;<br />
&nbsp;&nbsp;&nbsp; int <a href="#bvrect.top">top</a>;<br />
&nbsp;&nbsp;&nbsp; unsigned int <a href="#bvrect.width">width</a>;<br />
&nbsp;&nbsp;&nbsp; unsigned int <a href="#bvrect.height">height</a>;<br />
};</p>
<p class="Code_Header_2"><a name="bvrect.left">bvrect.left</a></p>
<p class="code_block">int left;</p>
<p>This member indicates the left edge of the rectangle, measured in pixels from the left edge of the surface.&nbsp; Note 
that this value <span class="underline">can</span> be negative, indicating that the rectangle begins before the left edge 
of the surface.&nbsp; However, this is only allowed when a rectangle is clipped to the surface.&nbsp; If, after clipping, 
the left edge of the rectangle is still negative, this is an error.</p>
<p class="Code_Header_2"><a name="bvrect.top">bvrect.top</a></p>
<p class="code_block">int top;</p>
<p>This member indicates the top edge of the rectangle, measured in lines of
<a href="#bfbuffdesc.virtstride" class="inline_code">bvbuffdesc.virtstride</a> bytes from the top edge of the surface.&nbsp; 
Note that this value <span class="underline">can</span> be negative, indicating that the rectangle begins before the top 
edge of the surface.&nbsp; However, this is only allowed when a rectangle is clipped to the surface.&nbsp; If, after clipping, 
the top edge of the rectangle is still negative, this is an error.</p>
<p class="Code_Header_2"><a name="bvrect.width">bvrect.width</a></p>
<p class="code_block">unsigned int width;</p>
<p>This member indicates the width of the rectangle, measured in pixels.&nbsp; Note that this value
<span class="underline">cannot</span> be negative.&nbsp; (Horizontal flipping is indicated using the
<span class="inline_code"><a href="#BVFLAG_HORZ_FLIP">BVFLAG_HORZ_FLIP_*</a></span> flags.)&nbsp; The value of this member 
may exceed the width of the associated surface.&nbsp; However, this is only allowed when a rectangle is clipped to the surface.&nbsp; 
If, after clipping, the right edge of the rectangle still exceeds the width of the surface, this is an error.</p>
<p class="Code_Header_2"><a name="bvrect.height">bvrect.height</a></p>
<p class="code_block">unsigned int height;</p>
<p>This member indicates the height of the rectangle, measured in lines of <span class="inline_code">
<a href="#bvbuffdesc.virtstride">bvbuffdesc.virtstride</a></span> bytes.&nbsp; Note that this value
<span class="underline">cannot</span> be negative.&nbsp; (Vertical flipping is indicated using the
<span class="inline_code"><a href="#BVFLAG_VERT_FLIP">BVFLAG_VERT_FLIP_*</a></span> flags.)&nbsp; The value of this member 
may exceed the width of the associated surface.&nbsp; However, this is only allowed when a rectangle is clipped to the surface.&nbsp; 
If, after clipping, the right edge of the rectangle still exceeds the height of the surface, this is an error.</p>
<hr />
<a name="bvcopparams" class="Code_Header">bvcopparams</a>
<p><span class="inline_code">bvcopparams</span> is used to define the cache operation to be performed by
<span class="inline_code"><a href="#bv_cache">bv_cache()</a></span>.</p>
<p class="small_code_block">struct bvcopparams {<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned int <a href="#bvcopparams.structsize">structsize</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvbuffdesc">struct bvbuffdesc</a> *<a href="#bvcopparams.desc">desc</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvsurfgeom">struct bvsurfgeom</a> *<a href="#bvcopparams.geom">geom</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvrect">struct bvrect</a>&nbsp;&nbsp;&nbsp;&nbsp; *<a href="#bvcopparams.rect">rect</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; enum bvcacheop&nbsp; <a href="#bvcopparams.cacheop">cacheop</a>;<br />
};</p>
<a name="bvcopparams.structsize" class="Code_Header_2">bvcopparams.structsize</a>
<p><span class="code_block">unsigned long structsize; /* input */</span></p>
<p>This member is used for compatibility between BLTsville versions.&nbsp; (See <span class="inline_code">
<a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
<p class="Code_Header_2"><a name="bvcopparams.desc">bvcopparams.desc</a></p>
<p class="code_block"><a href="#bvbuffdesc">struct bvbuffdesc</a> *desc;</p>
<p>This member points to the <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> of the surface for which 
the cache is being manipulated.&nbsp; This buffer should have been mapped with a call to <span class="inline_code">
<a href="#bv_map">bv_map()</a></span>.</p>
<p class="note">NOTE:&nbsp; Implementations may choose to dynamically map the surface as with <span class="inline_code">
<a href="#bv_blt">bv_blt()</a></span>, however in many systems, this will not function properly due to dynamic paging which 
can occur when a surface is not locked.</p>
<p><span class="Code_Header_2"><a name="bvcopparams.geom">bvcopparams.geom</a></span></p>
<p class="code_block"><a href="#bvsurfgeom">struct bvsurfgeom</a> *geom;</p>
<p>This member points to the <span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> of the surface for which 
the cache is being manipulated.</p>
<p><span class="Code_Header_2"><a name="bvcopparams.rect">bvcopparams.rect</a></span></p>
<p class="code_block"><a href="#bvrect">struct bvrect</a> *rect;</p>
<p>This member points to the <span class="inline_code"><a href="bvrect">bvrect</a></span> describing the rectangle of the 
surface which is being manipulated.</p>
<p><span class="Code_Header_2"><a name="bvcopparams.cacheop">bvcopparams.cacheop</a></span></p>
<p class="code_block">enum bvcacheop cacheop;</p>
<p>This member specifies the cache operation to be performed.&nbsp; It is an enumeration from the following list:</p>
<table style="" class="indent">
	<tr>
		<td><span class="inline_code"><a name="BVCACHE_BIDIRECTIONAL">BVCACHE_BIDIRECTIONAL</a></span></td>
		<td>(This usually performs a cache flush operation.)</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVCACHE_CPU_TO_DEVICE">BVCACHE_CPU_TO_DEVICE</a></span></td>
		<td>Performs the appropriate cache operation to ensure data can be transferred correctly when it was written with 
		the CPU, but will be read by the 2-D device.&nbsp; (This is usually a cache clean operation.)</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVCACHE_CPU_FROM_DEVICE">BVCACHE_CPU_FROM_DEVICE</a></span></td>
		<td>Performs the appropriate cache operation to ensure data can be transferred correctly when it was written by 
		the 2-D device, but will be read by the CPU.&nbsp; (This is usually a cache invalidate operation.)</td>
	</tr>
</table>
<br />
<hr />
<p class="Code_Header"><a name="bvbuffdesc">bvbuffdesc</a></p>
<p>This structure is used in conjunction with a <span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> structure 
to specify the characteristics of a graphic surface.&nbsp; This structure specifies the memory buffer itself.</p>
<p class="small_code_block">struct bvbuffdesc {<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned int <a href="#bvbuffdesc.structsize">structsize</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *<a href="#bvbuffdesc.virtaddr">virtaddr</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned long <a href="#bvbuffdesc.length">length</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bvbuffmap">struct bvbuffmap</a> *<a href="#bvbuffdesc.map">map</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; enum bvauxtype <a href="#bvbuffdesc.auxtype">auxtype</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *<a href="#bvbuffdesc.auxptr">auxptr</a>;<br />
};</p>
<p class="Code_Header_2"><a name="bvbuffdesc.structsize">bvbuffdesc.structsize</a></p>
<p class="code_block">unsigned int structsize;</p>
<p>This member is used for compatibility between BLTsville versions.&nbsp; (See <span class="inline_code">
<a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
<p class="Code_Header_2"><a name="bvbuffdesc.virtaddr">bvbuffdesc.virtaddr</a></p>
<p class="code_block">void *virtaddr;</p>
<p>This member is used to indicate the CPU virtual address of the start of the buffer.&nbsp; This value must be provided 
unless the <span class="inline_code"><a href="#bvbuffdesc.auxtype">auxtype</a></span>/<span class="inline_code"><a href="#bvbuffdesc.auxptr">auxptr</a></span> 
members below are used.&nbsp; At that time, this member is optional, and the <span class="inline_code">
<a href="#auxptr">auxptr</a></span> usually has higher priority than this member.</p>
<p class="imponly"><strong>Implementations Only</strong><br />
<br />
Note that this is always the beginning of the buffer.&nbsp; This means that if the <span class="inline_code">
<a href="#bvsurfgeom.virtaddr">bvsurfgeom.virtstride</a></span> is negative, or the <a href="#bvsurfgeom.orientation">bvsurfgeom.orientation</a> 
does not normalize to 0º&nbsp; (i.e. <span class="inline_code">orientation % 360 != 0</span>), implementations may need 
to use a modified version of <span class="inline_code">virtaddr</span> internally to operate correctly.</p>
<p class="Code_Header_2"><a name="bvbuffdesc.length">bvbuffdesc.length</a></p>
<p class="code_block">unsigned long length;</p>
<p>This member specifies the length of the buffer in bytes.</p>
<p class="note">NOTE:&nbsp; When used with a <span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> structure,
<span class="inline_code">length</span> should be greater than or equal to <span class="inline_code">
<a href="#bvsurfgeom.height">bvsurfgeom.height</a> * <a href="#bvsurfgeom.virtstride">bvsurfgeom.virtstride</a></span>.</p>
<p class="Code_Header_2"><a name="bvbuffdesc.map">bvbuffdesc.map</a></p>
<p class="code_block">struct bvbuffmap *map;</p>
<p>This member is used by the implementations and should <span class="underline"><strong>NEVER</strong></span> be manipulated 
by the client.&nbsp; When the <span class="inline_code">bvbuffdesc</span> structure is created, this member should be set 
to 0, indicating that no implementations have mapped the buffer.&nbsp; After a buffer has been mapped using a call to
<span class="inline_code"><a href="#bv_map">bv_map()</a></span>, this member should be left as-is by clients.&nbsp; (The 
implementation will set this back to 0 before returning from <span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span>.)</p>
<p class="imponly"><strong>Implementations Only</strong><br />
<br />
This member points to a linked list of <span class="inline_code"><a href="#bvbuffmap">bvbuffmap</a></span> structures associated 
with the buffer.&nbsp; Each <span class="inline_code"><a href="#bvbuffmap">bvbuffmap</a></span> is added to the list as 
the buffer is mapped by a given implementation.&nbsp; This may be done with an explicit call to
<span class="inline_code"><a href="#bv_map">bv_map()</a></span>, or implicitly with a call to <span class="inline_code">
<a href="#bv_blt">bv_blt()</a></span>, after a call to <span class="inline_code"><a href="#bv_map">bv_map()</a></span> from 
a different implementation.<br />
<br />
Implementations should not assume that the first entry in the list is their <span class="inline_code">
<a href="#bvbuffmap">bvbuffmap</a></span>.&nbsp; Instead, implementations should compare the <span class="inline_code">
<a href="#bv_unmap">bv_unmap()</a></span> pointer in the structure to their own function address.</p>
<p class="Code_Header_2"><a name="bvbuffdesc.auxtype">bvbuffdesc.auxtype</a></p>
<p class="code_block">enum bvauxtype auxtype;</p>
<p>This member is used to identify the type of additional information about the buffer provided by
<span class="inline_code"><a href="#bvbuffdesc.auxptr">auxptr</a></span>.&nbsp; Currently no values are defined for the 
user mode interface, so it should be initialized to 0 or <span class="inline_code">BVAT_NONE</span>.&nbsp; See the
<a href="#Kernel_Mode_Interface">Kernel Mode Interface</a> for details on the values defined for the kernel mode interface.</p>
<p class="Code_Header_2"><a name="bvbuffdesc.auxptr">bvbuffdesc.auxptr</a></p>
<p class="code_block">void *auxptr;</p>
<p>This member is used to point to additional information about the buffer.&nbsp; The type of this pointer is determined 
by the <span class="inline_code"><a href="#auxtype">auxtype</a></span> value.&nbsp; Currently there are no types defined 
for the user mode interface, so this member is ignored.&nbsp; See the <a href="#Kernel_Mode_Interface">Kernel Mode Interface</a> 
for details on the types defined for the kernel mode interface. </p>
<hr /><br />
<table style="" class="imponly">
	<tr>
		<td>
		<p><strong>Implementations Only</strong></p>
		<p class="Code_Header"><a name="bvbuffmap">bvbuffmap</a></p>
		<p>This structure is used from the bvbuffdesc.map member to allow implementations to associate their own data with 
		a buffer.</p>
		<p class="small_code_block"><span class="small_code_block_in_table">struct bvbuffmap {<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned int <a href="#bvbuffmap.structsize">structsize</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; BVFN_UNMAP <a href="#bvbuffmap.bv_unmap">bv_unmap</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned long <a href="#bvbuffmap.handle">handle</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; struct bvbuffmap *<a href="#bvbuffmap.nextmap">nextmap</a>;<br />
		};</span></p>
		<p class="Code_Header_2"><a name="bvbuffmap.structsize">bvbuffmap.structsize</a></p>
		<p class="code_block">unsigned int structsize;</p>
		<p>This member is used for compatibility between BLTsville versions.&nbsp; (See <span class="inline_code">
		<a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
		<p class="Code_Header_2"><a name="bvbuffmap.bv_unmap">bvbuffmap.bv_unmap</a></p>
		<p class="code_block">BVFN_UNMAP bv_unmap;</p>
		<p>This member holds the pointer to the <span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span> function 
		of the implementation associated with the <span class="inline_code">bvbuffmap</span> structure.&nbsp; It serves 
		to allow implementations to identify their <span class="inline_code">bvbuffmap</span> structure in the linked list, 
		as well as to allow implementations to call each other&#39;s <span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span> 
		calls from their own.</p>
		<p class="Code_Header_2"><a name="bvbuffmap.handle">bvbuffmap.handle</a></p>
		<p class="code_block">unsigned long handle;</p>
		<p>This member is used to hold an implementation-specific piece of data.</p>
		<p class="Code_Header_2"><a name="bvbuffmap.nextmap">bvbuffmap.nextmap</a></p>
		<p class="code_block">struct bvbuffmap *nextmap;</p>
		<p>This member holds a pointer to the next bvbuffmap structure in the linked list.&nbsp; If this member is 0, there 
		are no more entries in the list.<br />
		<br />
		<span class="note">NOTE:&nbsp; The Linux/Android Kernel Mode Interface differs slightly from this structure.&nbsp; 
		Refer to the <a href="#Kernel_Mode_Interface">Kernel Mode Interface</a> section for details.</span></p>
		</td>
	</tr>
</table>
<br />
<hr />
<p class="Code_Header"><a name="bvsurfgeom">bvsurfgeom</a></p>
<p>This structure is used in conjunction with a <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> structure 
to specify the characteristics of a graphic surface.&nbsp; This structure specifies the surface geometric characteristics.</p>
<p class="note">NOTE:&nbsp; This structure was separated from <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> 
to afford much flexibility to the client.&nbsp; Using the same <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> 
structure with different <span class="inline_code">bvsurfgeom</span> structures or using the same
<span class="inline_code">bvsurfgeom</span> structure with different <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> 
structures may be of benefit.&nbsp; See the <a href="#bvsurfgeom_examples">examples</a> at the bottom of this section.</p>
<p class="small_code_block">struct bvcopparams {<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned int <a href="#bvsurfgeom.structsize">structsize</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="http://graphics.github.com/ocd/">enum ocdformat</a> format;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned int width;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned int height;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int orientation;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; long virtstride;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="http://graphics.github.com/ocd/">enum ocdformat</a> paletteformat;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *palette;<br />
};</p>
<p class="Code_Header_2"><a name="bvsurfgeom.structsize">bvsurfgeom.structsize</a></p>
<p class="inline_code">unsigned int structsize;</p>
<p>This member is used for compatibility between BLTsville versions.&nbsp; (See <span class="inline_code">
<a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
<p class="Code_Header_2"><a name="bvsurfgeom.format">bvsurfgeom.format</a></p>
<p class="code_block"><a href="http://graphics.github.com/ocd/">enum ocdformat</a> format;</p>
<p>This member specifies the format of the surface using the <a href="http://graphics.github.com/ocd">Open Color format 
Definitions (OCD)</a>.</p>
<p class="Code_Header_2"><a name="bvsurfgeom.width">bvsurfgeom.width</a></p>
<p class="code_block">unsigned int width;</p>
<p>This member specifies the width of the surface in pixels.&nbsp; This size does not have to be equivalent to the
<span class="inline_code"><a href="#bvsurfgeom.virtstride">virtstride</a></span> size.</p>
<p class="imponly"><strong>Implementations Only</strong><br />
<br />
Implementations should never assume that <span class="inline_code">width</span> is equivalent to
<span class="inline_code"><a href="#bvsurfgeom.virtstride">virtstride</a></span>.</p>
<p class="Code_Header_2"><a name="bvsurfgeom.height">bvsurfgeom.height</a></p>
<p class="code_block">unsigned int height;</p>
<p>This member specifies the height of the surface in lines of <span class="inline_code">
<a href="#bvsurfgeom.virtstride">virtstride</a></span> width.</p>
<p class="Code_Header_2"><a name="bvsurfgeom.orientation">bvsurfgeom.orientation</a></p>
<p class="code_block">int orientation;</p>
<p>This member specifies the orientation or angle of the surface in degrees.&nbsp; Since BLTsville is designed only to specify 
orthogonal rectangles, this value must be a multiple of 90º.&nbsp; This value <span class="underline">may</span> be negative.&nbsp;
<em>(Extending BLTsville to handle non-orthogonal rectangles may be considered if there is sufficient interest.)</em></p>
<p class="imponly"><strong>Implementations Only</strong><br />
<br />
Implementations should normalize orientation angles.&nbsp; For example, a client that sets the orientation to -450º should 
behave as if the value of 270º were specified. </p>
<p class="Code_Header_2"><a name="bvsurfgeom.virtstride">bvsurfgeom.virtstride</a></p>
<p class="code_block">long virtstride;</p>
<p>This member specifies the horizontal stride of the surface in bytes for an unrotated surface.&nbsp; The stride represents 
the number of bytes needed to move from one pixel to the pixel immediately below it.&nbsp; This value
<span class="underline">may</span> be negative.</p>
<p class="note">NOTE:&nbsp; This means the <span class="inline_code">orientation</span> does not affect the
<span class="inline_code">virtstride</span>.&nbsp; However, rotating a surface usually results in a different configuration 
(i.e. <span class="inline_code">width</span>), which <span class="underline">will</span> affect the
<span class="inline_code">virtstride</span>.&nbsp; For example, a 320 x 240 x 32 bpp 0º surface might have a
<span class="inline_code">virtstride</span> of 1280 bytes (320 pixels/line * 32 bits/pixel / 8 bits/byte).&nbsp; When the 
orientation is set to 180º, the <span class="inline_code">virtstride</span> would be the same.&nbsp; But when the orientation 
is set to 90º (or 270º), the <span class="inline_code">virtstride</span> would most likely need to be set to 960 bytes (240 
pixels/line * 32 bits/pixel / 8 bits/byte). </p>
<p class="imponly"><strong>Implementations Only</strong><br />
<br />
Implementations that do not support a negative <span class="inline_code">virtstride</span> must compensate using whatever 
mechanism is appropriate for the implementation.&nbsp; For example, using a vertical flipping/mirroring setting.</p>
<p class="note">NOTE:&nbsp; The <span class="inline_code">virtstride</span> name must be maintained for backwards compatibility.&nbsp; 
However, no situation should arise where the client would need to provide two different strides for the virtual and physical 
views of a surface (there are situations where a physical stride will need to be available within the implementation, but 
the client will not be the one to supply it), so <em>physstride</em> will most likely never be needed.&nbsp; However, when 
a client provides a physical description of the buffer (see the <a href="#Kernel_Mode_Interface">Kernel Mode Interface</a> 
section below), the <span class="inline_code">virtstride</span> entry should be used to provide the physical stride.</p>
<p class="Code_Header_2"><a name="bvsurfgeom.paletteformat">bvsurfgeom.paletteformat</a></p>
<p class="code_block"><a href="http://graphics.github.com/ocd/">enum ocdformat</a> paletteformat;</p>
<p>This member specifies the format of the palette supplied via the <span class="inline_code">
<a href="#bvsurfgeom.palette">palette</a></span> member for palettized formats using the
<a href="http://graphics.github.com/ocd">Open Color format Definitions (OCD)</a>.</p>
<p class="Code_Header_2"><a name="bvsurfgeom.palette">bvsurfgeom.palette</a></p>
<p class="code_block">void *palette;</p>
<p>This member points to a palette used for palettized formats.&nbsp; The format of the palette is specified by the
<span class="inline_code"><a href="#bvsurfgeom.palette">paletteformat</a></span> member.&nbsp; Palettes are packed based 
on their container size:</p>
<table class="indent">
	<tr>
		<td class="ctr_thin_bord"><strong>Palette Format</strong></td>
		<td class="ctr_thin_bord"><strong>Palette Layout (byte address)</strong></td>
		<td class="ctr_thin_bord"><strong>Palette Layout (little endian)</strong></td>
	</tr>
	<tr class="small_code_block_in_table">
		<td class="thin_bord">OCDFMT_xRGB12</td>
		<td class="ctr_thin_bord">n/a</td>
		<td class="thin_bord">
		<table style="width: 100%">
			<tr>
				<td class="thin_bord">*(((unsigned short *)palette) + 0)</td>
				<td class="thin_bord">0xFrgb</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned short *)palette) + 1)</td>
				<td class="thin_bord">0xFrgb</td>
			</tr>
			<tr>
				<td class="thin_bord">...</td>
				<td class="thin_bord">...</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned short *)palette) + n - 1)</td>
				<td class="thin_bord">0xFrgb</td>
			</tr>
		</table>
		</td>
	</tr>
	<tr class="small_code_block_in_table">
		<td class="thin_bord">OCDFMT_RGB24</td>
		<td class="thin_bord">
		<table style="width: 100%">
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + 0)</td>
				<td class="thin_bord">red0</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + 1)</td>
				<td class="thin_bord">green0</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + 2)</td>
				<td class="thin_bord">blue0</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + 3)</td>
				<td class="thin_bord">red1</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + 4)</td>
				<td class="thin_bord">green1</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + 5)</td>
				<td class="thin_bord">blue1</td>
			</tr>
			<tr>
				<td class="thin_bord">...</td>
				<td class="thin_bord">&nbsp;</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + (3 * n) - 3)</td>
				<td class="thin_bord">redNm1</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + (3 * n) - 2)</td>
				<td class="thin_bord">greenNm1</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + (3 * n) - 1)</td>
				<td class="thin_bord">blueNm1</td>
			</tr>
		</table>
		</td>
		<td class="ctr_thin_bord">n/a</td>
	</tr>
	<tr class="small_code_block_in_table">
		<td class="thin_bord">OCDFMT_RGBx24</td>
		<td class="thin_bord">
		<table style="width: 100%">
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + 0)</td>
				<td class="thin_bord">red0</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + 1)</td>
				<td class="thin_bord">green0</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + 2)</td>
				<td class="thin_bord">blue0</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + 3)</td>
				<td class="thin_bord">0xFF</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + 4)</td>
				<td class="thin_bord">red1</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + 5)</td>
				<td class="thin_bord">green1</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + 6)</td>
				<td class="thin_bord">blue1</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + 7)</td>
				<td class="thin_bord">0xFF</td>
			</tr>
			<tr>
				<td class="thin_bord">...</td>
				<td class="thin_bord">&nbsp;</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + (4 * n) - 4)</td>
				<td class="thin_bord">redNm1</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + (4 * n) - 3)</td>
				<td class="thin_bord">greenNm1</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + (4 * n) - 2)</td>
				<td class="thin_bord">blueNm1</td>
			</tr>
			<tr>
				<td class="thin_bord">*(((unsigned char *)palette) + (4 * n) - 1)</td>
				<td class="thin_bord">0xFF</td>
			</tr>
		</table>
		</td>
		<td class="thin_bord">
		<table style="width: 100%">
			<tr>
				<td class="thin_bord">*(((unsigned long *)palette) + 0)</td>
				<td class="thin_bord">0xFFbbggrr<br />
				</td>
			</tr>
			<tr class="thin_bord">
				<td class="thin_bord">&nbsp;</td>
				<td class="thin_bord">&nbsp;</td>
			</tr>
			<tr class="thin_bord">
				<td class="thin_bord">&nbsp;</td>
				<td class="thin_bord">&nbsp;</td>
			</tr>
			<tr class="thin_bord">
				<td class="thin_bord">&nbsp;</td>
				<td class="thin_bord">&nbsp;</td>
			</tr>
			<tr class="thin_bord">
				<td class="thin_bord">*(((unsigned long *)palette) + 1)<br />
				</td>
				<td class="thin_bord">0xFFbbggrr<br />
				</td>
			</tr>
			<tr class="thin_bord">
				<td class="thin_bord">&nbsp;</td>
				<td class="thin_bord">&nbsp;</td>
			</tr>
			<tr class="thin_bord">
				<td class="thin_bord">&nbsp;</td>
				<td class="thin_bord">&nbsp;</td>
			</tr>
			<tr class="thin_bord">
				<td class="thin_bord">&nbsp;</td>
				<td class="thin_bord">&nbsp;</td>
			</tr>
			<tr class="thin_bord">
				<td class="thin_bord">...</td>
				<td class="thin_bord">&nbsp;</td>
			</tr>
			<tr class="thin_bord">
				<td class="thin_bord">*(((unsigned long *)palette) + n - 1)|<br />
				</td>
				<td class="thin_bord">0xFFbbggrr<br />
				</td>
			</tr>
			<tr class="thin_bord">
				<td class="thin_bord">&nbsp;</td>
				<td class="thin_bord">&nbsp;</td>
			</tr>
			<tr class="thin_bord">
				<td class="thin_bord">&nbsp;</td>
				<td class="thin_bord">&nbsp;</td>
			</tr>
			<tr class="thin_bord">
				<td class="thin_bord">&nbsp;</td>
				<td class="thin_bord">&nbsp;</td>
			</tr>
		</table>
		</td>
	</tr>
</table>
<p class="note">NOTE:&nbsp; Use of subsampled formats for <span class="inline_code">paletteformat</span> is currently undefined.</p>
<p class="Header4"><a name="bvsurfgeom_examples">Examples</a></p>
<p>Mixing and matching <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> and
<span class="inline_code">bvsurfgeom</span> structures provides maximum flexibility for a client.</p>
<table style="width: 100%" class="example">
	<tr>
		<td><strong>Example:</strong>&nbsp; Using two different <span class="inline_code">bvsurfgeom</span> structures with 
		the same <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> structure allows in-place format 
		conversion:</td>
	</tr>
	<tr>
		<td>
		<p class="indent"><span class="small_code_block_in_table">...<br />
		// Convert premultiplied image to non-premultiplied in place<br />
		struct
		bvbltparams parms;<br />
		...<br />
		struct
		bvbuffdesc buff;<br />
		...<br />
		struct
		bvsurfgeom srcgeom, dstgeom;<br />
		...<br />
		srcgeom.format = OCDFMT_RGBA24;<br />
		dstgeom.format = OCDFMT_nRGBA24;<br />
		...<br />
		parms.src1.desc = &amp;buff;<br />
		parms.src1geom = &amp;srcgeom;<br />
		parms.dstdesc = &amp;buff;<br />
		parms.dstgeom = &amp;dstgeom;<br />
		...<br />
		bv_blt(&amp;parms);<br />
		... </span></p>
		</td>
	</tr>
</table>
<br />
<table style="width: 100%" class="example">
	<tr>
		<td><strong>Example:</strong>&nbsp; Using three different <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> 
		structures with the same <span class="inline_code">bvsurfgeom</span> structure reduces code and copy errors:</td>
	</tr>
	<tr>
		<td>
		<p class="indent"><span class="small_code_block_in_table">...<br />
		// Blend two images of the same size<br />
		struct
		bvbltparams parms;<br />
		...<br />
		struct
		bvbuffdesc src1buff, src2buff, dstbuff;<br />
		...<br />
		struct
		bvsurfgeom geom;<br />
		...<br />
		parms.src1.desc = &amp;src1buff;<br />
		parms.src1geom = &amp;geom;<br />
		parms.src2.desc = &amp;src2buff;<br />
		parms.src2geom = &amp;geom;<br />
		parms.dstdesc = &amp;dstbuff;<br />
		parms.dstgeom = &amp;dstgeom;<br />
		...<br />
		bv_blt(&amp;parms);<br />
		... </span></p>
		</td>
	</tr>
</table>
<br />
<hr />
<p class="Code_Header"><a name="bvtileparams">bvtileparams</a></p>
<p>This structure is used to define the parameters necessary to use a small image as a tile or block that will be repeated 
when used as a source.&nbsp; This structure is used in conjunction with the associated <span class="inline_code">
<a href="#bvsurfgeom">bvsurfgeom</a></span> and the associated <span class="inline_code"><a href="#bvrect">bvrect</a></span> 
to determine the operation that is performed.</p>
<p class="small_code_block">struct bvcopparams {<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned int <a href="#bvtileparams.structsize">structsize</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned long <a href="#bvtileparams.flags">flags</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void *<a href="#bvtileparams.virtaddr">virtaddr</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int <a href="#bvtileparams.dstleft">dstleft</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int <a href="#bvtileparams.dsttop">dsttop</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned int <a href="#bvtileparams.srcwidth">srcwidth</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned int <a href="#bvtileparams.srcheight">srcheight</a>;<br />
};</p>
<p class="Code_Header_2"><a name="bvtileparams.structsize">bvtileparams.structsize</a></p>
<p class="code_block">unsigned int structsize;</p>
<p>This member is used for compatibility between BLTsville versions.&nbsp; (See <span class="inline_code">
<a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
<p class="Code_Header_2"><a name="bvtileparams.flags">bvtileparams.flags</a></p>
<p class="code_block">unsigned long flags;</p>
<p>This member specifies some additional information for the tiling operation.&nbsp; It can be composed as the binary OR 
of one selection for each edge (left, top, right, and bottom) from the following flags:</p>
<table style="" class="indent">
	<tr>
		<td><span class="inline_code"><a name="BVTILE_LEFT_REPEAT">BVTILE_LEFT_REPEAT</a></span></td>
		<td>indicates that the tile is repeated to the left of the destination alignment location.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVTILE_TOP_REPEAT">BVTILE_TOP_REPEAT</a></span></td>
		<td>indicates that the tile is repeated above the destination alignment location.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVTILE_RIGHT_REPEAT">BVTILE_RIGHT_REPEAT</a></span></td>
		<td>indicates that the tile is repeated to the right of the destination alignment location.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVTILE_BOTTOM_REPEAT">BVTILE_BOTTOM_REPEAT</a></span></td>
		<td>indicates that the tile is repeated below the destination alignment location.</td>
	</tr>
	<tr>
		<td><a name="BVTILE_LEFT_MIRROR" class="inline_code">BVTILE_LEFT_MIRROR</a></td>
		<td>indicates that the tile is mirrored to the left of the destination alignment location.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVTILE_TOP_MIRROR">BVTILE_TOP_MIRROR</a></span></td>
		<td>indicates that the tile is mirrored above the destination alignment location.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVTILE_RIGHT_MIRROR">BVTILE_RIGHT_MIRROR</a></span></td>
		<td>indicates that the tile is mirrored to the right of the destination alignment location.</td>
	</tr>
	<tr>
		<td><span class="inline_code"><a name="BVTILE_BOTTOM_MIRROR">BVTILE_BOTTOM_MIRROR</a></span></td>
		<td>indicates that the tile is mirrored below the destination alignment location.</td>
	</tr>
</table>
<p class="Code_Header_2"><a name="bvtileparams.virtaddr">bvtileparams.virtaddr</a></p>
<p class="code_block">void *virtaddr;</p>
<p>This member is used to indicate the CPU virtual address of the start of the buffer.</p>
<p class="imponly"><strong>Implementations Only</strong><br />
<br />
Note that this is always the beginning of the buffer.&nbsp; This means that if the <span class="inline_code">
<a href="#bvsurfgeom.virtaddr">bvsurfgeom.virtstride</a></span> is negative, or the <a href="#bvsurfgeom.orientation">bvsurfgeom.orientation</a> 
does not normalize to 0º&nbsp; (i.e. <span class="inline_code">orientation % 360 != 0</span>), implementations may need 
to use a modified version of <span class="inline_code">virtaddr</span> internally to operate correctly.</p>
<p class="Code_Header_2"><a name="bvtileparams.dstleft">bvtileparams.dstleft</a></p>
<p class="code_block">int dstleft;</p>
<p>This member is used to designate the left edge of the location of the tile in the destination for alignment purposes 
(alignment location).&nbsp; Note that the <span class="inline_code"><a href="#bvrect">bvrect</a></span> of the destination 
specifies the region which is filled by the tile.</p>
<p class="Code_Header_2"><a name="bvtileparams.dsttop">bvtileparams.dsttop</a></p>
<p class="code_block">int dsttop;</p>
<p>This member is used to designate the top edge of the location of the tile in the destination for alignment purposes (alignment 
location).&nbsp; Note that the <span class="inline_code"><a href="#bvrect">bvrect</a></span> of the destination specifies 
the region which is filled by the tile.</p>
<p class="Code_Header_2"><a name="bvtileparams.srcwidth">bvtileparams.srcwidth</a></p>
<p class="code_block">unsigned int srcwidth;</p>
<p>This member is used to designate the width of the source for purposes of scaling.&nbsp; The relationship between this 
field and the <span class="inline_code"><a href="#bvrect.width">bvrect.width</a></span> of the associated source surface 
determines the horizontal scaling factor.</p>
<p class="Code_Header_2"><a name="bvtileparams.srcheight">bvtileparams.srcheight</a></p>
<p class="code_block">unsigned int srcheight;</p>
<p>This member is used to designate the height of the source for purposes of scaling.&nbsp; The relationship between this 
field and the <span class="inline_code"><a href="#bvrect.height">bvrect.height</a></span> of the associated source surface 
determines the vertical scaling factor.</p>
<hr />
<p class="Code_Header"><a name="bvcallbackerror">bvcallbackerror</a></p>
<p>This structure is used to provide error information to the client of a BLT that failed within an asynchronous operation.&nbsp; 
The errors will be limited to those that occur within the implementation.</p>
<p class="note">NOTE:&nbsp; Parameter errors should never be returned in this structure.&nbsp; These should have been returned 
to the client before the BLT was ever initiated.</p>
<p class="small_code_block">struct bvcallbackerror {<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned int <a href="#bvcallbackerror.structsize">structsize</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bverror">enum bverror</a> <a href="#bvcallbackerror.error">error</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; char *<a href="#bvcallbackerror.errdesc">errdesc</a>;<br />
};</p>
<p class="Code_Header_2"><a name="bvcallbackerror.structsize">bvcallbackerror.structsize</a></p>
<p class="code_block">unsigned int structsize;</p>
<p>This member is used for compatibility between BLTsville versions.&nbsp; (See <span class="inline_code">
<a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
<p class="Code_Header_2"><a name="bvcallbackerror.error">bvcallbackerror.error</a></p>
<p class="code_block"><a href="#bverror">enum bverror</a> error;</p>
<p>This member is used to indicate the error encountered.&nbsp; In general, these will be error like these:</p>
<table class="indent">
	<tr>
		<td class="inline_code">BVERR_OP_FAILED</td>
		<td>The operation failed for unspecified reasons.&nbsp; The destination buffer was not modified.</td>
	</tr>
	<tr>
		<td class="inline_code">BVERR_OP_INCOMPLETE</td>
		<td>The operation only partially completed.&nbsp; The destination buffer is in an undefined state.</td>
	</tr>
	<tr>
		<td class="inline_code">BVERR_MEMORY_ERROR</td>
		<td>The operation resulted in a memory error, most likely due to an attempt to access invalid memory.&nbsp; The 
		destination buffer is in an undefined state.</td>
	</tr>
</table>
<p class="Code_Header_2"><a name="bvcallbackerror.errdesc">bvcallbackerror.errdesc</a></p>
<p class="code_block">char *errdesc;</p>
<p><span class="inline_code">errdesc</span> is optionally used by implementations to pass a 0-terminated string with additional 
debugging information back to clients for debugging purposes.&nbsp; <span class="inline_code">errdesc</span> is not localized 
or otherwise meant to provide information that is displayed to users.</p>
<hr />
<p class="Header1">Batching<a name="batching"></a></p>
<p>Batching is the single most powerful feature in BLTsville.&nbsp; It is used for two major purposes:</p>
<ol>
	<li>To group similar BLTs which use most of the same parameters so that they can be handled more efficiently by the 
	implementation.</li>
	<li>To group BLTs that should go together so that implementations can use special features that go beyond what seems 
	to be expressed by the BLTsville API.</li>
</ol>
<p class="note">NOTE:&nbsp; It is important to realize that BLTs batched together may be done <span class="underline">in 
any order</span>, and in fact may not even be done in the way specified.&nbsp; This includes the BLTs being done as they 
are submitted, or no operations performed until the batch submission is completed with
<a href="#BVFLAG_BATCH_END" class="inline_code">BVFLAG_BATCH_END</a>.&nbsp; This means the client must not rely on intermediate 
results within a batch.</p>
<p class="note">NOTE:&nbsp; Because BLTs can be performed in a variety of ways, callbacks for individual BLTs would have 
no consistent meaning.&nbsp; So, when batching is mixed with <span class="inline_code"><a href="#BVFLAG_ASYNC">BVFLAG_ASYNC</a></span>, 
only the callback for the last BLT occurs.</p>
<p class="note">NOTE:&nbsp; Since implementations can perform batched BLTs in a variety of ways, even synchronous batched 
BLTs can be effectively asynchronous.&nbsp; Therefore, only the last BLT determines the synchronicity of the entire batch.&nbsp; 
i.e. the <span class="inline_code"><a href="#BVFLAG_ASYNC">BVFLAG_ASYNC</a></span> flag is only heeded when combined with
<span class="inline_code"><a href="#BVFLAG_BATCH_END">BVFLAG_BATCH_END</a>.</span></p>
<p class="note">NOTE: Failure during the performance of a batch (different from an error on submission--indicated by the 
contents of the <a href="#bvcallbackerror" class="inline_code">bvcallbackerror</a> structure) will result in an unknown 
state for all destination buffers.&nbsp; Do not assume that a given implementation&#39;s state in this case represents the state 
which will be encountered for a different implementation.</p>
<p class="note">NOTE: Because of the indeterminate nature of the execution of a batch of BLTs, a &quot;batch abort&quot; would not 
result in a known state either.&nbsp; As stated above, a given implementation may have already performed earlier BLTs in 
a batch as the batch is submitted.&nbsp; So errors encountered during the submission of a batch must be handled by the client, 
and then the batch must be terminated normally using <a href="#BVFLAG_BATCH_END" class="inline_code">BVFLAG_BATCH_END</a>.</p>
<p class="Header2">Batches For Grouping Similar BLTs</p>
<p>Often, groups of similar BLTs are performed, with changes to only a few parameters.&nbsp; Some implementations have the 
ability to re-use previous settings, coupled with these changes, to perform new BLTs.</p>
<p>One good example of this in in rendering text, similar to that you are reading now.&nbsp; In most systems, a glyph cache 
is maintained to hold the characters of a given font, rasterized with the specific characteristics desired (e.g. bold, italics, 
etc.).&nbsp; Each font in the glyph cache is normally created using a font rasterization engine from a vector-based font, 
such as FreeType.&nbsp; This technology allows fonts to be described in terms of curves and lines instead of pixels, which 
means they can be created as needed, in any size desirable.</p>
<table style="" class="glyph_cache">
	<tr>
		<td class="glyph_cache">&nbsp; !&quot;#$%&amp;&#39;()*+&#39;-./0123456789:;&lt;=&gt;?<br />
		@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_<br />
		`abcdefghijklmnopqrstuvwxyz{|}~</td>
	</tr>
</table>
<p>Then, when a character needs to be rendered, it is copied from the pre-rendered glyph cache.&nbsp; This is much more 
efficient than performing the font rasterization from the vector description each time a character is used.</p>
<p>With some hardware implementations, the setup to trigger the copy of these characters from the glyph cache to the target 
surface can be quite significant, when compared to the number of pixels actually affected.&nbsp; For example, each character 
might consist of something on the order of&nbsp; 10 x 14, or about 140 pixels.&nbsp; Programming a typical hardware BLTer 
may require tens of commands for each character.</p>
<p>But note that each of these BLTs differs by only a few parameters.&nbsp; Specifically, once the source and destination 
surfaces have been specified, and the operation described, only the source and destination rectangles change between BLTs. 
To alleviate much of this overhead, most implementations will allow the configuration of a previous BLT to be used again, 
with only those parameters which change provided for the subsequent BLTs.</p>
<p>BLTsville provides access to this capability via the batch mechanism.</p>
<p>For rendering a word using a monospaced font like this, the client might construct the batch like this:</p>
<p class="small_code_block">struct bvbuffdesc screendesc = {sizeof(struct bvbuffdesc}, 0};<br />
struct bvsurfgeom screengeom = {sizeof(struct bvsurfgeom), 0};<br />
struct bvbuffdesc glyphcachedesc = {sizeof(struct bvbuffdesc), 0};<br />
struct bvsurfgeom glyphcachegeom = {sizeof(struct bvsurfgeom), 0};<br />
struct bvtileparams solidcolortileparams = {sizeof(struct bvtileparams), 0};<br />
struct bvbuffgeom solidcolorgeom = {sizeof(struct bvsurfgeom), 0};<br />
<br />
struct bvbltparams bltparams = {sizeof(struct bvbltparams), 0};<br />
<br />
int charsperline = 32;<br />
int fontwidth = 10;<br />
int fontheight = 14;<br />
int i = 0;<br />
<br />
screendesc.virtaddr = screenaddr;<br />
screendesc.length = screenstride * screenheight;<br />
screengeom.format = OCDFMT_RGB24;<br />
screengeom.width = screenwidth;<br />
screengeom.height = screenheight;<br />
screengeom.virtstride = screenstride;<br />
<br />
glyphcachedesc.virtaddr = glyphcacheaddr;<br />
glyphcachedesc.length = glyphcachestride * glyphcacheheight;<br />
glyphcachegeom.format = OCDFMT_ALPHA8;<br />
glyphcachegeom.width = glyphcachewidth;<br />
glyphcachegeom.height = glyphcacheheight;<br />
glyphcachegeom.virtstride = glyphstride;<br />
<br />
solidcolortileparams.virtaddr = &amp;solidcolor;<br />
solidcolortileparams.srcwidth = 1;<br />
solidcolortileparams.srcheight = 1;<br />
solidcolorgeom.format = OCDFMT_RGB24;<br />
<br />
bltparams.flags = BVFLAG_BLEND | BVFLAG_SRC1_TILED | BVFLAG_BATCH_BEGIN;<br />
bltparams.op.blend = BVBLEND_SRCOVER + BVBLENDDEF_REMOTE;<br />
bltparams.dstdesc = &amp;screendesc;<br />
bltparams.dstgeom = &amp;screengeom;<br />
bltparams.src1.tileparams = &amp;solidcolortileparams;<br />
bltparams.src1geom = &amp;solidcolorgeom;<br />
bltparams.src2.desc = &amp;screendesc;<br />
bltparams.src2geom = &amp;screengeom;<br />
bltparams.mask.desc = &amp;glyphcachedesc;<br />
bltparams.maskgeom = &amp;glyphcachegeom;<br />
<br />
bltparams.dstrect.left = bltparams.src2rect.left = screenrect.left;<br />
bltparams.dstrect.top = bltparams.src2rect.top = screenrect.top;<br />
<br />
bltparams.maskrect.width = bltparams.dstrect.width = bltparams.src2rect.width = fontwidth;<br />
bltparams.maskrect.height = bltparams.dstrect.height = bltparams.src2rect.height = fontheight;<br />
<br />
bltparams.maskrect.left = ((text[i] - &#39; &#39;) % charsperline) * fontwidth;<br />
bltparams.maskrect.top = ((text[i] - &#39; &#39;) / charsperline) * fontheight;<br />
<br />
bv_blt(&amp;bltparams);<br />
<br />
i++;<br />
if(i &lt; textlen)<br />
{<br />
&nbsp; bltparams.flags = (bltparams.flags &amp; ~BVFLAG_BATCH_MASK) | BVFLAG_BATCH_CONTINUE;<br />
&nbsp; bltparams.batchflags = BVBATCH_DSTRECT_ORIGIN | BVBATCH_SRC2RECT_ORIGIN | BVBATCH_MASKRECT_ORIGIN;<br />
<br />
&nbsp; do<br />
&nbsp; {<br />
&nbsp;&nbsp;&nbsp; bltparams.dstrect.left += fontwidth;<br />
&nbsp;&nbsp;&nbsp; bltparams.src2rect.left = bltparams.dstrect.left;<br />
<br />
&nbsp;&nbsp;&nbsp; bltparams.maskrect.left = ((text[i] - &#39; &#39;) % charsperline) * fontwidth;<br />
&nbsp;&nbsp;&nbsp; bltparams.maskrect.top = ((text[i] - &#39; &#39;) / charsperline) * fontheight;<br />
<br />
&nbsp;&nbsp;&nbsp; bv_blt(&amp;bltparams);<br />
<br />
&nbsp;&nbsp;&nbsp; i++;<br />
&nbsp; }while(i &lt; textlen);<br />
}<br />
<br />
bltparams.flags = (bltparams.flags &amp; ~BVFLAG_BATCH_MASK) | BVFLAG_BATCH_END;<br />
bltparams.batchflags = BVBATCH_ENDNOP;<br />
<br />
bv_blt(&amp;bltparams);</p>
<p class="note">NOTE:&nbsp; bvbltparams.batchflags is just a hit.&nbsp; Not all implementations support deltas in 
batching, so clients must not change the values of members of <span class="inline_code"><a href="#bvbltparams">
bvbltparams</a></span> (or structures it 
references) between BLTs.&nbsp; These values may be used.</p>
<p class="Header2">Batches For Special Feature BLTs</p>
<p>Enabling special features of some implementations is a special challenge.&nbsp; But BLTsville is up the task.</p>
<p>For example, perhaps an implementation is capable of blending four layers at the same time.&nbsp; But BLTsville only allows 
blending to be specified using two layers at a time.&nbsp; How can this be accomplished?</p>
<p>The most prevalent blending reference used is the <a href="http://dx.doi.org/10.1145/800031.808606">Porter-Duff 
whitepaper</a>, which specifies blending of two sources (A and B).&nbsp; So any N-source blend (N &gt; 2) would require the blends to be 
specified as a grouping of N - 1 two-source blends in order to utilize the 
Porter-Duff equations.&nbsp; That&#39;s how such a blend is specified in BLTsville:</p>
<p class="small_code_block">bltparams.dstrect.width = bltparams.src1rect.width = bltparams.src2rect.width = dstgeom.width;<br />
bltparams.dstrect.height = bltparams.src1rect.height = bltparams.src2rect.height = dstgeom.height; <br />
<br />
bltparams.flags = BVFLAG_BLEND | BVFLAG_BATCH_BEGIN;<br />
bltparams.op.blend = BVBLEND_SRCOVER;<br />
bltparams.dstdesc = &amp;dstdesc;<br />
bltparams.dstgeom = &amp;dstgeom;<br />
bltparams.src1.desc = &amp;src1desc;<br />
bltparams.src1geom = &amp;src1geom;<br />
bltparams.src2.desc = &amp;src2desc;<br />
bltparams.src2geom = &amp;src2geom;<br />
<br />
bv_blt(&amp;bltparams);<br />
<br />
bltparams.src1.desc = &amp;src3desc;<br />
bltparams.src1geom = &amp;src3geom;<br />
bltparams.dstdesc = &amp;dstdesc;<br />
bltparams.dstgeom = &amp;dstgeom;<br />
<br />
bltparams.flags = (bltparams.flags &amp; ~BVFLAG_BATCH_MASK) | BVFLAG_BATCH_CONTINUE;<br />
bltparams.batch = BVBATCH_SRC1 | BVBATCH_SRC2;<br />
<br />
bv_blt(&amp;bltparams);<br />
<br />
bltparams.src1.desc = &amp;src4desc;<br />
bltparams.src1geom = &amp;src4geom;<br />
<br />
bltparams.flags = (bltparams.flags &amp; ~BVFLAG_BATCH_MASK) | BVFLAG_BATCH_END;<br />
bltparams.batch = BVBATCH_SRC1;<br />
<br />
bv_blt(&amp;bltparams);</p>
<p>The driver for an implementation that can perform this pair of operations as one BLT would be tasked with recognizing 
that the batch contained BLTs which can be combined.</p>
<p>The fantastic thing about this approach is that an implementation without the ability to blend N sources in one pass would perform 
the blends separately, but the result would be identical.&nbsp; Moreover, implementations with the ability to combine 
different numbers of operations would likewise produce the same results, even they they used a different number of 
internal steps.&nbsp; Here&#39;s an example:</p>
<table align="center">
	<tr>
		<td>
<table>
	<tr>
		<td class="ctr_thin_bord"><strong>Number of<br />
		Layers to<br />
		Blend</strong></td>
		<td class="ctr_thin_bord"><strong>BLTsville<br />
		Operations</strong></td>
		<td class="ctr_thin_bord"><strong>Implementation<br />
		Capable of<br />
		Blending One<br />
		Source with a<br />
		Destination</strong><br />
				(2 inputs)</td>
		<td class="ctr_thin_bord"><strong>Implementation<br />
		Capable of<br />
		Blending Two<br />
		Sources to a<br />
		Destination</strong><br />
				(2 inputs)</td>
		<td class="ctr_thin_bord"><strong>Implementation<br />
		Capable of<br />
		Blending Four<br />
		Sources to a<br />
		Destination</strong><br />
				(4 inputs)</td>
		<td class="ctr_thin_bord"><strong>Implementation<br />
		Capable of<br />
		Blending Eight<br />
		Sources with<br />
		a Destination</strong><br />
		(5 inputs)</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">2</td>
		<td class="nowrap">A over B =&gt; O</td>
		<td class="nowrap">B =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">A over B =&gt; O</td>
		<td class="nowrap">A over B =&gt; O</td>
		<td class="nowrap">A over B =&gt; O</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">3</td>
		<td class="nowrap">B over C =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">C =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">B over C =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">A over B over C =&gt; O</td>
		<td class="nowrap">A over B over C =&gt; O</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">4</td>
		<td class="nowrap">C over D =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">D =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap"> C over D =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap"> A over B over C over D =&gt; O</td>
		<td class="nowrap"> A over B over C over D =&gt; O</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">5</td>
		<td class="nowrap">D over E =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">E =&gt; O<br />
		D over O =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">D over E =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">D over E =&gt; O<br />
		A over B over C over O =&gt; O</td>
		<td class="nowrap">E =&gt; O<br />
		A over B over C over D over O =&gt; O</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">6</td>
		<td class="nowrap">E over F =&gt; O<br />
		D over O =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">F =&gt; O<br />
		E over O =&gt; O<br />
		D over O =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">E over F =&gt; O<br />
		D over O =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">D over E over F =&gt; O<br />
		A over B over C over O =&gt; O</td>
		<td class="nowrap">E over F =&gt; O<br />
		A over B over C over D over O =&gt; O</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">7</td>
		<td class="nowrap">F over G =&gt; O<br />
		E over O =&gt; O<br />
		D over O =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">G =&gt; O<br />
		F over O =&gt; O<br />
		E over O =&gt; O<br />
		D over O =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">F over G =&gt; O<br />
		E over O =&gt; O<br />
		D over O =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">D over E over F over G =&gt; O<br />
		A over B over C over O =&gt; O</td>
		<td class="nowrap">E over F over G =&gt; O<br />
		A over B over C over D over O =&gt; O</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">8</td>
		<td class="nowrap">G over H =&gt; O<br />
		F over O =&gt; O<br />
		E over O =&gt; O<br />
		D over O =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">H =&gt; O<br />
		G over O =&gt; O<br />
		F over O =&gt; O<br />
		E over O =&gt; O<br />
		D over O =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">G over H =&gt; O<br />
		F over O =&gt; O<br />
		E over O =&gt; O<br />
		D over O =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">G over H =&gt; O<br />
		D over E over F over O =&gt; O<br />
		A over B over C over O =&gt; O</td>
		<td class="nowrap">E over F over G over H =&gt; O<br />
		A over B over C over D over O =&gt; O</td>
	</tr>
	<tr>
		<td class="ctr_thin_bord">9</td>
		<td class="nowrap">H over I =&gt; O<br />
		G over O =&gt; O<br />
		F over O =&gt; O<br />
		E over O =&gt; O<br />
		D over O =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">I =&gt; O<br />
		H over O =&gt; O<br />
		G over O =&gt; O<br />
		F over O =&gt; O<br />
		E over O =&gt; O<br />
		D over O =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">H over I =&gt; O<br />
		G over O =&gt; O<br />
		F over O =&gt; O<br />
		E over O =&gt; O<br />
		D over O =&gt; O<br />
		C over O =&gt; O<br />
		B over O =&gt; O<br />
		A over O =&gt; O</td>
		<td class="nowrap">G over H over I =&gt; O<br />
		D over E over F over O =&gt; O<br />
		A over B over C over O =&gt; O</td>
		<td class="nowrap">I =&gt; O<br />
		E over F over G over H over O =&gt; O<br />
		A over B over C over D over O =&gt; O</td>
	</tr>
</table>
</td>
	</tr>
	<tr>
		<td class="ctr">Comparison of batched BLTsville calls with internal operations, based on implementation capabilities.
</td>
	</tr>
</table>
<p class="note">NOTE: As mentioned above a batch of BLTs may be serviced in any number of ways.&nbsp; In this example, the 
destination buffer may be used for intermediate results, so it is important that this buffer not be used during the batch--i.e. 
as a displayed buffer.</p>
<hr />
<p class="Header1"><a name="start">Where to Start</a></p>
<p><em>(Note that error checking is omitted in all the examples below for clarity.)</em> </p>
<p>1.&nbsp; Clients begin by opening one or more BLTsville implementations dynamically.&nbsp; The specific method of doing 
this is dependent on the operating system.&nbsp; For example, Linux might do this like this:</p>
<p class="small_code_block">struct bltsvillelib<br />
{<br />
&nbsp; char* name;<br />
&nbsp; void* handle;<br />
&nbsp; BVFN_MAP bv_map;<br />
&nbsp; BVFN_BLT bv_blt;<br />
&nbsp; BVFN_UNMAP bv_unmap;<br />
}; <br />
<br />
struct bltsville bvlib[] =<br />
{<br />
&nbsp; { &quot;libbltsville_cpu.so&quot;, 0 },<br />
&nbsp; { &quot;libbltsville_2d.so&quot;, 0 }<br />
};<br />
const int NUMBVLIBS = sizeof(bvlib) / sizeof(struct bltsvillelib);<br />
<br />
for(int i = 0; i &lt; NUMLIBS; i++)<br />
{<br />
&nbsp; bvlib[i].handle = dlopen(bvlib[i].name, RTLD_LOCAL | RTLD_LAZY);<br />
&nbsp; bvlib[i].bv_map = (BVFN_MAP)dlsym(bvlib[i].handle, &quot;bv_map&quot;);<br />
&nbsp; bvlib[i].bv_blt = (BVFN_BLT)dlsym(bvlib[i].handle, &quot;bv_blt&quot;);<br />
&nbsp; bvlib[i].bv_unmap = (BVFN_BLT)dlsym(bvlib[i].handle, &quot;bv_unmap&quot;);<br />
}<br />
</p>
<p>2.&nbsp; Clients then need to create a <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> object for 
each buffer to be accessed in BLTsville:</p>
<table class="indent">
	<tr>
		<td valign="top">
		<p class="small_code_block_in_table">struct bvbuffdesc buff =<br />
&nbsp; {sizeof(struct bvbuffdesc), 0};<br />
		<br />
		buff.virtaddr = buffptr;<br />
		buff.length = bufflength;</p>
		</td>
		<td class="ctr">&nbsp;or&nbsp</td>
		<td valign="top">
		<p class="inline_code"><span class="small_code_block_in_table">struct bvbuffdesc buff;<br />
		<br />
		memset(&amp;buff, 0, sizeof(buff));<br />
		buff.structsize = sizeof(buff);<br />
		buff.virtaddr = buffptr;<br />
		buff.length = bufflength;</span></p>
		</td>
	</tr>
</table>
<p class="strong_emphasis">Note that the client must ensure that the map element and any additional members in
<span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> are initialized to 0.</p>
<p>3.&nbsp; Next the buffer can be mapped to give the hardware implementations a chance to associate any necessary resources 
with the buffer:</p>
<table class="indent">
	<tr>
		<td valign="top">
		<p class="small_code_block_in_table">/* do nothing */ </p>
		</td>
		<td class="ctr">&nbsp;or&nbsp;</td>
		<td valign="top">
		<p class="small_code_block_in_table">bvlib[0].bv_map(&amp;buff); </p>
		</td>
		<td class="ctr">&nbsp;or&nbsp;</td>
		<td valign="top">
		<p class="small_code_block_in_table">for(int i = 0; i &lt; NUMLIBS; i++)<br />
		{<br />
&nbsp; if(bvlib[i].bv_map)<br />
&nbsp;&nbsp;&nbsp; bvlib[i].bv_map(&amp;buff);<br />
		}</p>
		</td>
	</tr>
</table>
<br />
<table style="width: 100%">
	<tr>
		<td valign="top">a. </td>
		<td>This step is actually optional, as indicated above.&nbsp; However, if the client does not explicitly call
		<span class="inline_code"><a href="#bv_map">bv_map()</a></span>, the mapping must be done by the implementation 
		to associate the necessary resources with the buffer.&nbsp; So this mapping must be done later, when
		<span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> is called.&nbsp; Additionally, since the client 
		did not call <span class="inline_code"><a href="#bv_map">bv_map()</a></span>, it is unlikely that the client will 
		call <span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span> to allow the implementation to free the 
		resources associated with the buffer.&nbsp; So the implementation will internally unmap the resources after completing 
		the BLT.&nbsp; This means that the mapping and unmapping overhead will be encountered on every call to
		<span class="inline_code"><a href="#bv_blt">bv_blt()</a></span>.<br />
		<em><br />
		In general, the CPU implementations have (almost) no overhead associated with mapping and unmapping.&nbsp; So opting 
		not to make the <span class="inline_code"><a href="#bv_map">bv_map()</a></span> call for CPU implementations is 
		likely to have negligible difference in <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> performance.<br />
		</em></td>
	</tr>
	<tr>
		<td valign="top">b. </td>
		<td>Calling <span class="inline_code"><a href="#bv_map">bv_map()</a></span> once for each buffer is enough to tell 
		the implementations that the client can be trusted to call <span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span> 
		when work with the buffer is complete, as indicated above.&nbsp; It does not matter which implementation&#39;s
		<span class="inline_code"><a href="#bv_map">bv_map()</a></span> is called.&nbsp; However, that implementation is 
		the only one which will perform the mapping immediately.&nbsp; All other implementations will perform a <em>lazy 
		mapping</em> only when their <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> call is invoked.<br />
		<br />
		This allows the client to avoid the overhead of mapping and unmapping the buffers on each
		<span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> call.&nbsp; It also avoids the associated mapping 
		and unmapping overhead if a given implementation is never used.<br />
		<br />
		<em>As mentioned above, the CPU implementations have (almost) no overhead associated with mapping and unmapping, 
		so they are a good choice to use for the call to <span class="inline_code"><a href="#bv_map">bv_map()</a></span>.<br />
		</em></td>
	</tr>
	<tr>
		<td valign="top">c. </td>
		<td>If the client wants direct control over the mapping and unmapping overhead, it can call the
		<span class="inline_code"><a href="#bv_map">bv_map()</a></span> function of each implementation, as indicated above.&nbsp; 
		Each implementation will perform the mapping at that time, so that the overhead will not appear on subsequent calls 
		to <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span>. </td>
	</tr>
</table>
<p>4.&nbsp; Next the client must create <span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> objects for 
each way in which a buffer will be accessed.&nbsp; Often, there is only one way in which a buffer is accessed, so there 
will be the same number of buffers, <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span>, and
<span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> objects.&nbsp; If that&#39;s the case, it may be convenient 
for the client to combine them into a parent structure.&nbsp; It may even be possible to share a single bvbuffgeom structure 
among buffers.&nbsp; Or there will be times when it is necessary to treat a buffer in different ways for different BLTs.&nbsp; 
Having these two structures separated allows all of these combinations.</p>
<table class="indent">
	<tr>
		<td valign="top">
		<p class="small_code_block_in_table">struct bvsurfgeom geom =<br />
&nbsp; {sizeof(struct bvsurfgeom), 0};<br />
		<br />
		geom.format = OCDFMT_RGB24;<br />
		geom.width = width;<br />
		geom.height = height;<br />
		geom.virtstride = stride;</p>
		</td>
		<td class="ctr">&nbsp;or&nbsp;</td>
		<td valign="top">
		<p class="inline_code"><span class="small_code_block_in_table">struct bvsurfgeom geom;
		<br />
		memset(&amp;geom, 0, sizeof(geom));<br />
		geom.structsize = sizeof(geom);<br />
		geom.width = width;<br />
		geom.height = height;<br />
		geom.virtstride = stride;</span></p>
		</td>
	</tr>
</table>
<p class="strong_emphasis">Note that the client must ensure that any additional members in <span class="inline_code">
<a href="#bvsurfgeom">bvsurfgeom</a></span> are initialized to 0 for future compatibility.</p>
<p>5.&nbsp; Now the client is ready to fill in a bvbltparams structure to specify the type of BLT requested.&nbsp; Here 
is an example of a simple copy from the lower right corner of a surface to the upper left:</p>
<p class="small_code_block">struct bvbltparams bltparams = {sizeof(struct bvbltparams), 0};<br />
<br />
bltparams.flags = BVFLAG_ROP;<br />
bltparams.op.rop = 0xCCCC; /* SRCCOPY */<br />
bltparams.dstdesc = &amp;buff;<br />
bltparams.dstgeom = &amp;geom;<br />
bltparams.dstrect.left = 0;<br />
bltparams.dstrect.top = 0;<br />
bltparams.dstwidth = width / 2;<br />
bltparams.dstheight = height / 2;<br />
bltparams.src1.desc = &amp;buff;<br />
bltparams.src1geom = &amp;geom;<br />
bltparams.src1rect.left = width / 2;<br />
bltparams.src1rect.top = height / 2;<br />
bltparams.src1rect.width = width / 2;<br />
bltparams.src1rect.height = height / 2;</p>
<p>6.&nbsp; And next the client can trigger the BLT by calling <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span>:</p>
<p class="small_code_block">bv_blt(&amp;bltparams); </p>
<p><em>If the client cannot complete the requested BLT, it returns a </em><span class="inline_code"><a href="#bverror">
<em>bverror</em></a></span><em> indicating the issue. </em></p>
<p>7.&nbsp; Finally, the client should clean up:</p>
<p class="small_code_block">bv_unmap(&amp;buff); </p>
<hr />
<p class="Header1"><a name="Kernel_Mode_Interface">Kernel Mode Interface</a></p>
<p>The kernel mode interface differs only slightly from the user mode interface.&nbsp; Currently there are two differences 
in the general kernel interface, and one in the Linux/Android interface:</p>
<p class="Code_Header_2">bvbuffdesc.auxtype/auxptr</p>
<p><span class="inline_code"><a href="#bvbuffdesc.auxtype">bvbuffdesc.auxtype</a></span> is an <span class="inline_code">enum</span>, 
indicating the type of the
<span class="inline_code"><a href="#bvbuffdesc.auxptr">bvbuffdesc.auxptr</a></span>.&nbsp; The enumeration values and 
the associated types are:</p>
<table class="indent_thick_bord">
	<tr>
		<td class="thin_bord_dbl_botbord"><span class="inline_code"><a href="#bvbuffdesc.auxtype">bvbuffdesc.auxtype</a></span></td>
		<td class="thin_bord_dbl_botbord">
<span class="inline_code"><a href="#bvbuffdesc.auxptr">bvbuffdesc.auxptr</a></span> type</td>
		<td class="thin_bord_dbl_botbord">Notes</td>
	</tr>
	<tr>
		<td class="thin_bord"><span class="inline_code"><a name="BVAT_PHYSDESC">BVAT_PHYSDESC</a></span></td>
		<td class="thin_bord">
<a href="#bvphysdesc" class="inline_code">bvphysdesc</a></td>
		<td class="thin_bord">Used to specify the physical pages of a physically discontiguous buffer constructed using 
		a single page size.&nbsp; This may be used with physically contiguous buffers as well, but
		<span class="inline_code"><a href="#BVAT_PHYSADDR">BVAT_PHYSADDR</a></span> is preferred.</td>
	</tr>
	<tr>
		<td class="thin_bord"><span class="inline_code"><a name="BVAT_PHYSADDR">BVAT_PHYSADDR</a></span></td>
		<td class="thin_bord">physical address</td>
		<td class="thin_bord">Used to specify the starting physical address of a physically contiguous buffer.</td>
	</tr>
</table>
<p>The methods of describing the buffer using physical addresses is not exposed in user mode for security reasons.</p>
<hr />
<p class="Code_Header"><a name="bvphysdesc">bvphysdesc</a></p>
<p class="small_code_block">struct bvphysdesc {<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned int <a href="#bvphysdesc.structsize">structsize</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned long <a href="#bvphysdesc.pagesize">pagesize</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned long *<a href="#bvphysdesc.pagearray">pagearray</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned int <a href="#bvphysdesc.pagecount">pagecount</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned long <a href="#bvphysdesc.pageoffset">pageoffset</a>;<br />
};</p>
<p class="Code_Header_2"><a name="bvphysdesc.structsize">bvphysdesc.structsize</a></p>
<p class="code_block">unsigned int structsize;</p>
<p>This member is used for compatibility between BLTsville versions.&nbsp; (See <span class="inline_code">
<a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
<p class="Code_Header_2"><a name="bvphysdesc.pagesize">bvphysdesc.pagesize</a></p>
<p class="code_block">unsigned long pagesize;</p>
<p>This member indicates the size of the physical pages containing the buffer.&nbsp; <span class="inline_code">BVAT_PHYSDESC</span>/<span class="inline_code">bvphysdesc
</span>does not support buffers which reside in pages that are not all the same size.&nbsp; <span class="inline_code">
bvphysdesc.pagesize</span> is used to indicate the length of the pages in the <span class="inline_code">
<a href="#bvphysdesc.pagearray">bvphysdesc.pagearray</a></span> as well as the expected alignment of those pages.&nbsp; If this value is 0, the default 
page size of the system is assumed.</p>
<p class="note">NOTE:&nbsp; When used with physically contiguous buffers, this member should be set to the length of the 
buffer, which is the same as the value in <span class="inline_code"><a href="#bvbuffdesc.length">bvbuffdesc.length</a></span>.</p>
<p class="Code_Header_2"><a name="bvphysdesc.pagearray">bvphysdesc.pagearray</a></p>
<p class="code_block">unsigned long *pagearray;</p>
<p>This member is an array of <span class="inline_code">unsigned long</span>s holding the physical addresses of the pages 
holding the buffer.&nbsp; The array contains <span class="inline_code"><a href="#bvphysdesc.pagecount">pagecount</a></span> 
entries.&nbsp; The specific format of the physical addresses is O/S dependent.&nbsp; However, <span class="inline_code">
BVAT_PHYSDESC</span>/<span class="inline_code">bvphysdesc</span> only supports 32-bit physical addresses.</p>
<p>Addresses in this array must be aligned on <span class="inline_code"><a href="#bvphysdesc.pagesize">
bvphysdesc.pagesize</a></span> boundaries.&nbsp; Use the <span class="inline_code"><a href="#bvphysdesc.pageoffset">
bvphysdesc.pageoffset</a></span> member to indicate the offset from the start of the first page to the beginning of the 
buffer.</p>
<p class="note">NOTE:&nbsp; When used with physically contiguous buffers, the first (only) address in this array should 
be aligned on the system default page boundary, and the <span class="inline_code"><a href="#bvphysdesc.pageoffset">
bvphysdesc.pageoffset</a></span> member should be used to indicate the offset from that address to the beginning of the 
buffer.</p>
<p class="Code_Header_2"><a name="bvphysdesc.pagecount">bvphysdesc.pagecount</a></p>
<p class="code_block">unsigned int pagecount;</p>
<p>This member indicates the number of pages in the array pointed to by <span class="inline_code">
<a href="#bvphysdesc.pagearray">bvphysdesc.pagearray</a></span>.</p>
<p class="note">NOTE:&nbsp; When used with physically contiguous buffers, this member should be set to 1.</p>
<p class="Code_Header_2"><a name="bvphysdesc.pageoffset">bvphysdesc.pageoffset</a></p>
<p class="code_block">unsigned long pageoffset;</p>
<p>This member indicates the number of bytes from the start of the first page (<span class="inline_code">*pagearray</span>) 
to the start of the buffer.&nbsp; The value must be less than <span class="inline_code"><a href="#bvphysdesc.pagesize">
bvphysdesc.pagesize</a></span>.</p>
<p class="imponly"><strong>Implementations Only</strong><br />
<br />
Implementations should not ignore this member.</p>
<hr />
<p class="Header2">bventry</p>
<p>Kernel mode entry cannot be the same as the user mode.&nbsp; The specific method of accessing the kernel interface is 
O/S specific.&nbsp; However, the following interface is currently defined for the specified O/Ss:</p>
<table class="example">
	<tr>
		<td>
		<p class="Header4">Linux/Android</p>
		<p class="Code_Header"><a name="bventry">bventry</a></p>
		<p>This structure is used to obtain the pointers to the implementation&#39;s BLTsville calls.&nbsp; The client can call 
		the default <span class="inline_code">bv2d_entry()</span> function to obtain the pointers to the implementation 
		chosen by the system integrators, or it can call a specific function to get the pointers for a specific implementation 
		(e.g. <span class="inline_code">gcbv_entry()</span>).</p>
		<p class="small_code_block">struct bventry {<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned int <a href="#bventry.structsize">structsize</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bv_map">BVFN_MAP</a> <a href="#bventry.bv_map">bv_map</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bv_unmap">BVFN_UNMAP</a> <a href="#bventry.bv_unmap">bv_unmap</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bv_blt">BVFN_BLT</a> <a href="#bventry.bv_blt">bv_blt</a>;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#bv_cache">BVFN_CACHE</a> <a href="#bventry.bv_cache">bv_cache</a>;<br />
		};</p>
		<p class="Code_Header_2"><a name="bventry.structsize">bventry.structsize</a></p>
		<p class="code_block">unsigned int structsize;</p>
		<p>This member is used for compatibility between BLTsville versions.&nbsp; (See <span class="inline_code">
		<a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
		<p class="Code_Header_2"><a name="bventry.bv_map">bventry.bv_map</a>/<a name="bventry.bv_unmap">bv_unmap</a>/<a name="bventry.bv_blt">bv_blt</a>/<a name="bventry.bv_cache">bv_cache</a></p>
		<p class="code_block">BVFN_MAP bv_map;<br />
		BVFN_UNMAP bv_unmap;<br />
		BVFN_BLT bv_blt;<br />
		BVFN_CACHE bv_cache;</p>
		<p>These members hold pointers to the functions for the specific implementation queried with a call to
		<span class="inline_code">*_entry()</span>.</p>
		<p class="note">NOTE:&nbsp; <span class="inline_code"><a href="#bv_cache">bv_cache()</a></span> is optional, so 
		this pointer may be set to 0.</p>
		</td>
	</tr>
</table>
<br />
<hr /><br />
<p class="Header2">Linux/Android Deviation</p>
<p>Although the linked list used in the <span class="inline_code"><a href="#bvbuffmap">bvbuffmap</a></span> structure is 
not complicated, there may be a requirement to use the standard Linux/Android kernel linked list in that environment.&nbsp; 
To facilitate this, the <span class="inline_code"><a href="#bvbuffmap.map">bvbuffmap.map</a></span> entry is replaced by 
the following entry for Linux/Android <span class="underline">kernel mode only</span>:</p>
<p class="Code_Header"><a name="bvbuffmap.node" class="Code_Header_2">bvbuffmap.node</a></p>
<p class="code_block">struct list_head node;</p>
<p>This member is used to reference the containing linked list for the <span class="inline_code"><a href="#bvbuffmap">bvbuffmap</a></span> 
structures associated with the buffer.</p>

</body>

</html>
